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Software 


OS/2 End User 
Advantages 

Dave Dill 
IBM Corporation 
Dallas , Texas 

Operating System/2™ (OS/2) is 
IBM's newest multitasking operat¬ 
ing system for use with 80286™-, 
80386™-, and 80486™-based per¬ 
sonal computers. This article de¬ 
scribes the user requirements 
that led to the development of 
OS/2 and why a multitasking oper¬ 
ating system is so important in 
today s complex business environ¬ 
ment. It also looks at the produc¬ 
tivity benefits available to users 
of OS/2, both from the operating 
system itself and from new appli¬ 
cations developed for the Presen¬ 
tation Manager™ user interface of 
OS/2. 

Several years ago a nationwide ham¬ 
burger chain commissioned a series 
of advertisements that featured a lit¬ 
tle old lady who drove her automo¬ 
bile around to the competitor’s 
hamburger restaurants. After elbow¬ 
ing her way to the counter, she de¬ 
manded in a loud voice, “Where’s 
the beef?” As sometimes happens 
with clever advertising campaigns, 
selected phrases remain and become 
part of the language long after the 
commercials have disappeared. 
“Where’s the beef?” became one of 
those expressions, a phrase indicat¬ 
ing a desire for quality in products 
and services. 

It’s surprising that in today’s world 
of complex hardware and software. 


most of us have forgotten the 
phrase, “Where’s the beef?” We 
seem to accept a torrent of technical 
details as evidence that this or that 
product is superior. We seldom ask 
what impact the product will have 
on employees, how the product will 
improve employee productivity, or 
what kind of training and support 
the product will require. Simply 
put, when it comes to personal com¬ 
puter hardware and software, we no 
longer seem to care where the beef 
is. 




The fact is that the OS/2 operating 
system can make users more produc¬ 
tive. This article highlights, in ev¬ 
eryday terms, the gains available to 
end users from OS/2 Extended Edi¬ 
tion. The approach is non-techni- 
cal, explaining the value of OS/2 
without requiring an understanding 
of bus architecture, DMA address¬ 
ing or other technical details. I 
often wonder if the little old lady in 
the hamburger commercials would 


have been satisfied with an explana¬ 
tion of the atomic structure of ham¬ 
burger buns when she asked her 
famous question. 


The Original PC 
Assumptions 

Many people feel that OS/2 is un¬ 
necessary, that DOS with its modifi¬ 
cations and extensions will suffice 
as an operating system for many 
years to come. After all, they rea¬ 
son, DOS has never been more pop¬ 
ular than it is today, it continues to 
grow and be enhanced, and its appli¬ 
cations continue to be updated. 



To understand why IBM and 
Microsoft felt it necessary to invest 
millions of dollars and thousands of 
hours in the development of a new 
operating system, it is necessary to 
understand the original DOS require¬ 
ments. 


Normally, when IBM considers de¬ 
veloping a new product, the existing 
market is surveyed to understand 
how the proposed product might be 
used. However, in the case of plan¬ 
ning the original IBM Personal 
Computer, there was no existing 
market to survey, because there 
were no existing PC users in the 
business world. In place of a de¬ 
tailed survey of users, and because 
an understanding of the intended 
market is vital to building any prod¬ 
uct, IBM developed a series of as¬ 
sumptions about how the PC would 
be used, who would use it, what 
they would use it for, and where it 
would be used. There were hun¬ 
dreds of assumptions covering all as¬ 
pects of PC use, but for our 
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purposes there were four fundamen¬ 
tal assumptions made that resulted 
in limiting the use of DOS in 
today’s sophisticated business envi¬ 
ronment. 

A Single Machine Running One 
Program at a Time: First, it was 
assumed that the original PC would 
be a single-user machine and that 
DOS would run only one program 
at a time. The key phrase here is 
“one program at a time” - not a pro¬ 
gram and an emulator, or a program 
and a utility, or a program and a 
Terminate-and-Stay-Resident rou¬ 
tine, but one program at a time. 

This assumption, more than any 
other, allowed DOS to be relatively 
simple in structure. 

With only one program running at a 
time, there could be, by definition, 
only one outstanding interrupt at 
any time and, thus, no requirement 
for re-entrant code in the operating 
system or the hardware BIOS. 

When a program requests service 
via an interrupt, that program is sus¬ 
pended until the service is com¬ 
pleted; in a system with only one 
program running, servicing of that 
suspended program’s request is the 
only work to be done. DOS was 
kept simple and small by enforcing 
this single outstanding interrupt con¬ 
cept. 

Limited Memory and I/O 
Requirements: Second, these ma¬ 
chines were designed for limited 
memory and I/O requirements. 

Most PCs had 64 KB of memory; 
some went as high as 96 KB or 
even 128 KB. Most applications, 
however, were built to run in a ma¬ 
chine with only 64 KB of memory, 
including space for DOS, so there 
was certainly no need for a sophisti¬ 
cated memory management routine. 
When a program was started, all 
memory was allocated to that pro¬ 


gram, and if that program didn’t re¬ 
lease any memory, there was no 
room for any other program to run. 
The I/O requirements ranged from 
none, which required no diskette 
storage, to a maximum of two 160 
KB, single-sided, diskette drives. 
With these minimal data storage re¬ 
quirements, DOS disk routines did 
not need to be sophisticated or opti¬ 
mized. After all, when the maxi¬ 
mum user data available was 160 
KB, and DOS occupied the other 
drive, how sophisticated did the 
disk routines need to be? 

A Limited Marketplace: Third, 
and very important, was the assump¬ 
tion that PCs would be used only by 
computer-literate people. It was 
never expected that PCs would 
come into such general use that 
they would be given to people who 
did not fully understand how the 
hardware or the operating system 
works. PCs were intended for a nar¬ 
rowly focused market, with only a 
few hundred thousand PCs pro¬ 
jected to be sold over the product’s 
life. No company was expected to 
have more than five or ten PCs at 
any one location, and these would 
be in key areas, run by people spe¬ 
cially trained to operate and pro¬ 
gram them. For these 
knowledgeable users, the “C” 
prompt is not only user-friendly, but 
is the best user interface possible be¬ 
cause it is the quickest and easiest 
way to work with a PC. The “C” 
prompt is not “unfriendly,” it just is 
not “friendly” to the people who 
wound up using PCs. If businesses 
had not insisted on putting PCs on 
secretaries’ desks, on shipping 
docks, on manufacturing lines and 
on executives’ desks, there would 
have been no problem with the user 
interface. But businesses did, and 
now there is. 


No Communication Requirements: 

Finally, PCs were never intended to 
be communicating devices. They 
were designed as stand-alone ma¬ 
chines. IBM did offer an asynchro¬ 
nous communication card with the 
original machines, but communica¬ 
tions, especially high-speed commu¬ 
nications to a host device with the 
accompanying data-transfer require¬ 
ments, were never considered an op¬ 
tion. If users needed data from a 
host device, it was assumed they 
would use a 3270-type terminal to 
query the host, then key the re¬ 
turned data into the PC. As a result, 
DOS never had a requirement to 
support communications. There¬ 
fore, since the PC’s first days, users 
have an emulator, which is an oper¬ 
ating system extension, to handle 
their communication requirements. 

The Requirement For OS/2 

All these assumptions were invali¬ 
dated on the first day the PC be¬ 
came available, because the 
business community began to 
change the way it did business 
based upon the productivity poten¬ 
tial of the PC. Of all the changes 
made, three stand out when consid¬ 
ering the viability of DOS and the 
original marketing assumptions. 

A Change in the Way Data Is 
Processed: Corporations quickly 
discovered that the PC gave the peo¬ 
ple who need to process data the 
ability to do their own processing. 
This made them significantly more 
productive and responsive to the 
needs of the business. If the person 
who needs the data has control over 
how and when to process the data, 
the results will be more accurate 
and timely. The PC freed users 
from the scheduling problems of 
host machines. If they needed re¬ 
sults on a particular day or data pro¬ 
cessed in a special way, they had 
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the power to do it themselves. But 
this placed a tremendous burden on 
communications between the PC 
and the host. In order to do all this 
customized processing, huge 
amounts of raw, or unprocessed, 
data had to flow between the host 
and thousands of remote PCs. 

Businesses also began to change the 
type of processing that they did 
with their PCs. The first PCs ran 
small record-keeping applications, 
such as accounts payable, accounts 
receivable and payroll. Programs 
were easy to use, and the amount of 
data processed was small. Today, 
businesses are turning toward fore¬ 
casting what will happen rather than 
recording what did happen. For in¬ 
stance, businesses today want to 
know what will happen to their mar¬ 
ket share if they raise their advertis¬ 
ing budget 10 percent and their 
competition doesn’t follow suit. To 
do this, businesses began buying or 
building complex economic models 
to help forecast the future of their 
products and businesses. But this 
has caused a gigantic growth in the 
requirements for data. These mod¬ 
els require vast amounts of informa¬ 
tion to accurately forecast the 
future, and the data required is no 
longer simple and straightforward. 

Most host machines are consumed 
with the normal daily work and can¬ 
not always be as responsive as users 
might like. Rather than try to force 
their host machines to be more re¬ 
sponsive, businesses have discov¬ 
ered that it is easier and cheaper to 
give personal computers to the peo¬ 
ple needing the data processed and 
allow them to set the requirements 
and do the processing. The prob¬ 
lem with this is that it became no 
longer possible to forecast accu¬ 
rately when users will need access 
to data or what data they will need. 
Data has now become an “on-de¬ 


mand” item. When the user needs 
data, the host must supply it. 

Users have also changed the type of 
data they process. The original PCs 
were designed for text data, and 
DOS was built to display and pro¬ 
cess text data. In fact, IBM did not 
offer a graphics monitor when the 
PCs were first introduced. Today, 
however, graphics data is the norm, 
rather than the exception, with busi¬ 
ness charting, desktop publishing, 
computer aided design (CAD) and 
the like. These exciting graphics ap¬ 
plications place tremendous demand 



There is a real need 
to connect every user 
to every source of data 


on PC memory. To hold a single 
page of data scanned at 400 dots 
per inch and in 16 colors or shades 
of gray can consume from 8 to 12 
million bytes of memory, depending 
on the viewing options. DOS was 
not designed to handle this much 
data - it lacks the internal routines 
to move massive amounts of screen 
data and also lacks the large mem¬ 
ory support needed to handle this 
much data. 

Finally, corporations have begun to 
transform their hosts into giant 
“data utilities.” Like the utilities 
that supply electricity when the user 
throws the switch, hosts are now ex¬ 
pected to supply data when the user 
throws the data-transfer switch. 

This has placed a tremendous strain 
on communication networks. Be¬ 
cause hosts never know when or 
how much communication capabil¬ 


ity they will need, they often must 
plan for the maximum. 

A Growing Emphasis On 
Communications: Businesses have 
come to realize that, after the actual 
products they build or sell, data is 
their most important asset and ac¬ 
cess to the data, wherever it is, is ab¬ 
solutely critical for those with 
authorization to use it. 

Data is now a “company-wide” re¬ 
source that must be accessible by ev¬ 
eryone with a “need to know,” 
regardless of where he or she is lo¬ 
cated. The idea that developed sev¬ 
eral years ago with the introduction 
of local area networks, that data is 
unique and could be kept entirely 
within a department, has been 
proved wrong. A company cannot 
predict who will need what data or 
where it will be needed. As a re¬ 
sult, there is a real need to connect 
every user to every source of data. 
This amounts to connecting every 
user to every other user and to 
every host machine. Needless to 
say, this has caused tremendous de¬ 
mands on communications. 

Furthermore, because computers in 
use today were made by several 
manufacturers, the standard IBM 
SNA communication network may 
not be sufficient. Users often need 
to run a variety of communication 
protocols concurrently. Ethernet™, 
TCP/IP, X.25, and seven-bit asyn¬ 
chronous are just a few of the ways 
companies connect their own com¬ 
puters and connect to computers in 
other companies. For DOS users, 
this is a nightmare. Most DOS emu¬ 
lators do not support multiple con¬ 
current communication disciplines. 

As a result, DOS users often require 
multiple emulators - none of which 
run concurrently, each with different 
keyboards, different interfaces and 
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different data-transfer protocols - to 
perform their daily work. 

The Proliferation Of 
Workstations: One of the assump¬ 
tions about the original PC and 
DOS design was that the PC would 
only be used by computer-literate 
people who knew how the hardware 
and software worked. These users 
were considered sophisticated 
enough to support themselves; train¬ 
ing and after-installation support 
were not required for them. After 
all, what support is needed by users 
who write their own applications, 
may have modified the DOS operat¬ 
ing system, and can strip, repair and 
reassemble a broken PC in about an 
hour? These were the intended 
users of PCs. 

This, however, is not the way the 
market has developed. PCs and 
their follow-on Personal System/2® 
(PS/2) machines have been moved 
into every comer of most busi¬ 
nesses. Employees of every skill 
level within most companies now 
have computers available and are ex¬ 
pected to mold at least part of their 
jobs around their computers. This 
presents companies with real prob¬ 
lems, because this new breed of 
users requires extensive training and 
after-installation support. They do 
not have the expertise to support 
themselves. Many less sophisti¬ 
cated users have been given so 
much automation that they require 
support to perform anything but the 
most standard of functions. This 
has led to huge increases in support 
staffs and a large increase in related 
costs. 

Productivity Gains From 
OS/2 

How can business users running 
under DOS solve all these prob¬ 
lems? Some relief is offered by 


OS/2 itself, by what can be called 
the OS/2 environment, while addi¬ 
tional relief is offered by new appli¬ 
cations written to use the OS/2 and 
Presentation Manager (PM) inter¬ 
faces. Each of these areas offers its 
own productivity enhancements for 
users. 



The productivity gains available 
from the OS/2 environment (sepa¬ 
rate from gains available from the 
OS/2 and PM interfaces) are due to 
two things: the ability to address 
up to 16 MB of memory, and the 
ability to have more than one task 
running at a time. This does not 
mean there are only two productiv¬ 
ity gains for users. To the contrary, 
there are many different ways to in¬ 
crease productivity under OS/2, but 
all of the benefits available from the 
OS/2 environment relate in some 
way to these two features. 

Rapid Access To Required 
Applications: One way a user can 
benefit from large memory address¬ 
ing is to load more than one applica¬ 
tion at a time. With more than one 
application running, the applications 
appear interruptible, and users can 
choose which applications get their 


attention and when to move from 
one application to another. This is 
an important feature of the OS/2 op¬ 
erating system, because it lets the 
user select what to run and when to 
run it. 

DOS certainly allows the user to se¬ 
lect what to run, but once an appli¬ 
cation is started, the computer is 
unavailable for the duration of the 
application. Anyone who has ever 
formatted a diskette knows that 
while the format program is run¬ 
ning, the PC cannot do additional 
work. This can be extremely frus¬ 
trating to users. Copying large 
amounts of data to diskettes pres¬ 
ents the same problem. Once the 
copy is started, the user must wait 
for the copy to complete before any¬ 
thing else can be run, regardless of 
the user’s requirements. This unpro¬ 
ductive time is the main reason 
most users don’t back up their hard 
drives - they cannot afford the 45 
to 90 minutes the backup requires, 
time their PCs are unavailable for 
other things. 

It is not enough to talk about run¬ 
ning more than one application at a 
time, without also mentioning the 
background processing capability of 
OS/2. Background processing is 
the ability to run applications out of 
the user’s sight. This gives the user 
the benefit of the application with¬ 
out having to deal with the complex¬ 
ities of the application or the 
problems of running multiple con¬ 
current applications. The user can 
select applications from a menu and 
ignore the required support pro¬ 
grams running in the background. 
Imagine transferring data without 
having to deal with the transfer pro¬ 
gram; browsing a bulletin board 
without having to deal with the 
asynchronous communication task; 
or creating a report from a database 
without having to deal with the data 
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extraction program. In contrast, al¬ 
though DOS can jump from one ap¬ 
plication to another, the DOS user is 
aware of all of the running applica¬ 
tions and must deal with each of 
them at some point in their execu¬ 
tion. 

Individual Applications Can Use 
Memory More Efficiently: A sec¬ 
ond way productivity can benefit 
from large memory addressing is 
the ability of individual applications 
to acquire large amounts of memory 
for their own use. Significant gains 
in performance can be achieved by 
applications when a large amount of 
the data they use can be held in 
memory at one time. Sorting, ex¬ 
tracting, analyzing, drawing and ma¬ 
nipulating data are significantly 
faster when the application does not 
have to swap large amounts of the 
data continuously to disk because of 
limited amounts of available mem¬ 
ory. Applications heavily depen¬ 
dent upon data can run up to 50 
percent faster under OS/2, which 
has the ability to address more mem¬ 
ory and thus hold more data. 

If you have ever run into the 
spreadsheet message “no more mem¬ 
ory,” or tried to spell-check a large 
document when only a few pages 
could fit into memory at one time, 
or tried to manipulate a scanned 
image under DOS when only a few 
hundred thousand bytes of memory 
were available to hold the image, 
you know the frustration users feel 
with the DOS limited memory envi¬ 
ronment. There is just not enough 
room under DOS for today’s sophis¬ 
ticated data applications. 

Today, with the DOS operating sys¬ 
tem, users are trying to cope with 
limited memory by using one of a 
number of memory-management 
routines. The problem is these rou¬ 
tines often require specially written 


applications, special hardware, or 
unique drivers that may not coexist 
with other hardware or drivers. In 
short, under DOS, managing the 
amounts of memory required by 
today’s applications is difficult and 
frustrating at best. 

Reduced Execution Time 
Through Better Storage 
Management: The third benefit 
from OS/2’s ability to address up to 
16 MB of memory is the reduced 
complexity of applications. This re¬ 
duced complexity means faster and 
easier development and quicker exe¬ 
cution. Applications running under 
OS/2 can have a single large main 
module that eliminates the need to 
manage a complex overlay struc¬ 
ture. With OS/2, the operating sys¬ 
tem handles the allocation of free 
memory and the transfer of unused 
program code to disk when memory 
is overcommitted. Applications can 
be optimized for faster execution 
when the need to manage a com¬ 
plex overlay structure is removed. 

Everyone has at some time strug¬ 
gled under DOS with slow-running 
applications that had to manage 
complex structures and large data 
areas, and with programs that had to 
move overlays into and out of mem¬ 
ory trying to keep up with the user. 
Everyone has experienced the delay 
between the time a PF key was 
pressed and the time the function 
was ready for use. These delays 
come from the need to compress 
millions of bytes of logic into rela¬ 
tively small overlays. Not only is 
the overall program complex with 
its need to manage overlays and 
pass data, but each overlay itself be¬ 
comes more complex, because it 
must manage the interaction with all 
other overlays. 


Overlap Long-Running Tasks Or 
Subtasks: In addition to large mem¬ 
ory addressing, productivity gains 
within the OS/2 environment come 
from multitasking, which is the abil¬ 
ity to run more than one application 
at a time, and multithreading, which 
is the ability of a single application 
to have more than one logic path ex¬ 
ecuting at a time. However, the pro¬ 
ductivity gains from multitasking 
and multithreading require more 
than just running two applications at 
a time. The user must take care to 
find the right mix of jobs so that 
those running in the background can 
execute with little or no user in¬ 
volvement. It would do little good 
to run multiple spreadsheets, for ex¬ 
ample, because the spreadsheets run¬ 
ning in the background would 
receive little user attention and pro¬ 
duce few, if any, results. 

Communications and host data trans¬ 
fer are prime examples of good 
background applications. They are 
usually long-running functions, 
often they can be automated, they 
usually do not require user input to 
produce the desired results, and 
they often appear complex to users. 
Consider any application that uses 
data from a host computer. Data 
transfer becomes part of that appli¬ 
cation, not because the application 
requires it, but because of the need 
to position the data at the PC. As a 
result, the user becomes involved in 
this process which is not easy to un¬ 
derstand and often time-consuming. 
For some applications, the time to 
transfer the data exceeds the time to 
run the application. For those appli¬ 
cations, wouldn’t it be convenient to 
transfer the data automatically as a 
by-product of turning on the PC? 
With OS/2, this can be done easily 
by starting a background task that 
transfers the data from the host 
prior to the time the application is 
to run, making the data available 
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without user involvement, and sav¬ 
ing the transfer time. 

But many businesses need more 
than the traditional host SNA link. 
They need local area network links, 
asynchronous communication links, 
links to public networks, and links 
to non-IBM computers, all in addi¬ 
tion to their traditional IBM host 
links. If a business is involved in a 
“just-in-time” inventory system with 
its suppliers, it may need links to its 
suppliers’ computers because 
tomorrow’s raw materials are on the 
suppliers’ shop floor today. To un¬ 
derstand the work in progress, the 
business needs to know what its sup¬ 
pliers will deliver, and that takes au¬ 
tomated links to be productive. 

DOS emulators do not support 
these concurrent multiprotocol 
links, but OS/2 does, and they all 
can run in the background if re¬ 
quired. Three or four communica¬ 
tion links running in the background 
that supply data automatically to a 
production application running in 
the foreground can be a very power¬ 
ful productivity tool. 

Often users will dispute the produc¬ 
tivity of multitasking because their 
machines are dedicated to running 
one application. They may, in fact, 
believe that multitasking will im¬ 
prove productivity, but feel it 
doesn’t apply to their particular cir¬ 
cumstances. After all, they reason, 
how productive can multitasking be 
when they run the same text process¬ 
ing program all day long? But over¬ 
lapping the same application within 
the same machine can be very pro¬ 
ductive. DOS cannot do this over¬ 
lapping, but OS/2 can. 

Think about most PCs with dedi¬ 
cated applications. Regardless of 
the application, there are natural 
wait-periods in every application, 
periods when the machine is busy 


and the operator is left with nothing 
to do. Text processing is an excel¬ 
lent example of this. Sooner or 
later, the need to print high-quality 
documents will bring the PC to a 
stop while the documents print. 

Even with background printing, 
there are still occasions when man¬ 
aging data and printing will cause 
the PC to wait, making the operator 
unproductive. Wouldn’t it be more 
productive if, after starting one of 
these long-printing applications, the 
operator moved to another OS/2 ses¬ 
sion, re-executed the same text ap¬ 
plication, and began to work with 
another document? The operator 
might well have several sessions 
running, each executing the same 
application but working on different 
documents. By allowing the opera¬ 
tor to keep working during those 
wait-periods, OS/2 has increased the 
operator’s productivity significantly. 

Run Multiple Parts Of A Job 
Simultaneously: Ask most users 
what they do with their personal 
computers and they will tell you 
they run something “big” like gen¬ 
eral ledger, accounts receivable, 
sales analysis or desktop publishing. 
In other words, users tend to think 
of what they do as one large applica¬ 
tion running for a long time; produc¬ 
tivity gains are hard to extract from 
long-running tasks. The fact is, 
however, they really are running 
many small tasks that, when put to¬ 
gether, make up the overall applica¬ 
tion. Within any application, data 
input, file updating, sorting, print¬ 
ing, and other functions are usually 
found. All of these steps make up 
the big application. But users do 
not see the individual parts, because 
under DOS it makes no difference 
in overall time how they arrange the 
individual tasks. The sum of the in¬ 
dividual tasks is equal to the time of 
the application. 


With OS/2, however, rearranging 
the individual tasks often leads to 
greater productivity. Overlapping 
the longer-running tasks with one or 
more shorter tasks can effectively 
eliminate the time of the shorter 
tasks. For example, when an appli¬ 
cation contains a relatively long-run¬ 
ning data search routine, start it first 
so it can be overlapped with shorter 
report preparation activities. If data 
needs to be downloaded from a host 
computer, do that while preparing 
your final documentation. If you 
can overlap a five-minute data trans¬ 
fer during a 30-minute application, 
you have increased your productiv¬ 
ity by 17 percent. 

Applications can automatically start 
overlapped subtasks via multithread¬ 
ing to achieve significant productiv¬ 
ity gains. When an individual step 
will take a relatively long time to 
complete, the application can auto¬ 
matically start a second thread that 
will run at its own pace while con¬ 
trol is returned to the user. The user 
can then shift to another part of the 
application or another application to 
keep working while the secondary 
thread completes. These productiv¬ 
ity gains can occur automatically 
without the user having to rearrange 
the schedule of execution. 

Probably the best example of task 
overlap is a background communica¬ 
tion task automatically collecting 
data and feeding it to a foreground 
task. The user may never know that 
the background task is running, yet 
the data automatically appears 
within the foreground application. 
Imagine sitting in front of a 
spreadsheet and seeing the data you 
need appear within the spreadsheet 
automatically, continually refreshing 
itself to show the most current data 
at all times. The user needs to 
know nothing about communica¬ 
tions, data transfer, cut-and-paste or 
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clipboards to achieve gains in pro¬ 
ductivity from such an application. 

Overlap Key Applications With 
Less Important Applications: 

The key to real productivity gains is 
keeping the users focused on what 
is important to them. Most users 
get paid to do select things; throw¬ 
ing lots of “windows” at users will 
not make them more productive if 
the important functions get lost in 
the crowd. 

If the user’s job is to manage a com¬ 
pany asset with a spreadsheet, then 
the spreadsheet should be kept cen¬ 
tered on the screen at all times. For 
this user, everything else is second¬ 
ary. OS/2 can make the user more 
productive by making the 
spreadsheet more productive, but 
the focus must remain on the 
spreadsheet. All users - from secre¬ 
taries to loading-dock personnel to 
order-entry clerks - need to keep fo¬ 
cused on the applications that are 
key to them. 

This presents an opportunity: the 
background execution and multi¬ 
threading capabilities of OS/2 keep 
users focused on what is important 
to them. Users are relieved of the re¬ 
sponsibility of running and control¬ 
ling the lesser tasks and can 
concentrate on what they get paid to 
do. 

Productivity Gains From 
OS/2 and PM Applications 

Productivity gains come not only 
from the OS/2 environment, but 
also from applications written espe¬ 
cially for the Presentation Manager. 
This is where the gains become 
more unique to each user and the ap¬ 
plications produce real magic. The 
magic comes from hiding the mun¬ 
dane and complex functions in the 
background so users see only the 


data they need in the applications 
they are running. The productivity 
gains available when writing Presen¬ 
tation Manager applications come 
from the increased sophistication 
and integration of the applications. 

More Sophisticated And 
Integrated Applications: There 
are hundreds of new and exciting ca¬ 
pabilities built into OS/2, the Com¬ 
munications Manager, Database 
Manager and Presentation Manager. 
We have already touched on a few. 
But the availability of multithread¬ 
ing, data piping, dynamic data ex¬ 
change, and named pipes means 
new and better ways to write appli¬ 
cations. Users should look for new 
ways to do business, rather than just 
think of running the same old DOS 
applications under OS/2. 

Sophisticated applications executing 
multiple logical paths simulta¬ 
neously within the same application 
hold exciting potential for programs 


that border on artificial intelligence. 
Applications can now completely 
modify their execution patterns 
based upon received data. The user 
no longer needs to be knowledge¬ 
able in all aspects of an application, 
because the application can automat¬ 
ically compensate for a changing en¬ 
vironment by executing alternate 
logical paths. The application can 
now make many of the decisions 
that formerly were made by the 
user. Applications can be in com¬ 
munication with multiple host loca¬ 
tions and multiple vendors to make 
intelligent decisions about inventory 
and product movements, while the 
user simply enters the order into the 
personal computer. 

Easier To Use 

With all the sophistication possible 
with OS/2 applications, it is impor¬ 
tant to note that for most users, the 
Presentation Manager environment 
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is easier to use than DOS. The stan¬ 
dardized graphics interface means: 

• All applications look and operate 
the same. Navigating around one 
application is the same as navigat¬ 
ing around all of them. Support 
and training are reduced. New 
applications look just like exist¬ 
ing applications. 

• All possible user actions are dis¬ 
played on the screen in easy-to- 
use menus and dialog boxes. 

The user is not left to guess what 
to do next. 

• A sophisticated help feature can 
be made available for every ac¬ 
tion the user is required to take, 
and all help works the same, re¬ 
gardless of the application, be¬ 
cause it is now a function of the 
operating system. 

• Background processing can re¬ 
move the complex and difficult 
functions from user control re¬ 
quiring less application-specific 
knowledge by the user. 

Easier And Faster 
Application Development 

Don’t overlook the cost and time in¬ 
volved in developing applications 
under OS/2 and the Presentation 
Manager. The cost of application 
development should include design, 
development, and writing as well as 
the maintenance. While it may be 
cheaper today to develop an applica¬ 
tion under DOS, considering that 80 
percent of an application’s cost in¬ 
volves ongoing maintenance, the 
OS/2 application will almost always 
be cheaper over the life of an appli¬ 
cation. 


No matter how well programmers 
write DOS applications, they will 
face maintenance problems. A new 
version of DOS, a change in the 
DOS interrupt structure, new and 
larger emulators, new shells and 
menuing systems, and growth in the 
data or movement of the data - 
these are some of the events beyond 
the control of the programmer that 
will surface early in the life of a 
DOS application and will require 
maintenance. 

OS/2 avoids many of these prob¬ 
lems by using architected interfaces 
that are serviced through loose calls 
rather than a tight register bind. Be¬ 
cause OS/2 provides significantly 
more services than DOS, program¬ 
mers need not write application 
code to perform what should be an 
operating system function; and the 
less code, the less maintenance. 

The use of Dynamic Link libraries 
means one executing routine can be 
shared by all programs that need it. 
There is no more need for copy 
books and no more need to recom¬ 
pile and link the hundreds of appli¬ 
cations that use the same book. 
Instead, write it once; compile it 
once; and maintain it once. That’s 
true productivity for programmers. 

The missing pieces for meaningful 
OS/2 and PM application develop¬ 
ment are now beginning to arrive. 
OS/2 Programming Tools and Infor¬ 
mation Version 1.2 contains new 
high-level language support that al¬ 
lows easier control of the PM envi¬ 
ronment so that programmers not 
familiar with C or Macro Assembler 
can code in COBOL or FORTRAN. 
A sophisticated procedure language 
will be added to OS/2 with Ex¬ 
tended Edition version 1.2. And 
new PM coding tools and applica¬ 


tion development systems are avail¬ 
able that allow programmers to 
build applications without the need 
to master PM coding techniques. 

Summary 

These are not the only productivity 
gains available to users running 
under OS/2 and the Presentation 
Manager. These are not even most 
of the potential gains available. 

There are almost as many productiv¬ 
ity gains available from OS/2 and 
the Presentation Manager as there 
are different applications. This arti¬ 
cle simply suggests some of the 
more common productivity gains 
available to users. Some of these 
gains may apply in a particular situa¬ 
tion and some may not; none are ab¬ 
solute. But a look at existing 
applications should show' the poten¬ 
tial for enormous productivity gains 
from the OS/2 operating system, the 
Presentation Manager, the Commu¬ 
nication Manager™ and the 
Database Manager. 
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What’s New in 
OS/2 Standard 
Edition 
Version 1.2? 


Craig Chambers 
IBM Corporation 
Dallas, Texas 

This is a summary of the new fea¬ 
tures in Operating System/2 
(OS/2) Standard Edition (SE) Ver¬ 
sion 1.2. 

Version 1.2 of OS/2 SE continues 
the improvements begun with the in¬ 
clusion of the Presentation Manager 
in OS/2 SE Version 1.1. These im¬ 
provements give version 1.2 a com¬ 
pletely new look and make it 
considerably easier to use than pre¬ 
vious versions. Improvements in¬ 
clude visual items such as 3-D push 
buttons, a new Desktop Manager 
and online reference system, a 
buffer for commands, and a greatly 
improved File Manager. 

The new online command reference 
is an installation option. If users 
have questions about how to use a 
command, its format, or the mean¬ 
ing of its parameters, entering 
HELP will prompt the system to 
display a complete description of 
that command. 

With all of these changes and en¬ 
hancements, OS/2 Version 1.2 now 
requires 12 MB of disk space if all 
features are installed. 

Desktop Manager 

The Task Manager and Start Pro¬ 
grams windows have been replaced 
with a new window called the 
Desktop Manager. 
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Programs are arranged into groups 
which are listed in the Desktop Man¬ 
ager window. These groups can ei¬ 
ther be opened automatically when 
the system is started, or can be 
started by the user. Within a group, 
programs can be started just as they 
were in version 1.1 by clicking on 
them with the mouse pointer or 
highlighting them by moving the ac¬ 
tion bar and hitting the enter key. 

One interesting new feature is the 
ability to start DOS programs in the 
DOS compatibility session from the 
program groups under the Desktop 
Manager or the File Manager. 

The group windows can be arranged 
anywhere on the screen. A new op¬ 
tion of the Desktop Manager allows 
the user to save the screen arrange¬ 
ment. When the system is restarted, 
the screen is arranged just as it was 
when it was saved. 

Programs can be moved between 
the various groups by simply click¬ 
ing on them with the mouse pointer 
and dragging them to a different 
group. The order of the programs 
with the list in a group can be 
changed the same way; click on the 
program and drag it to the location 
in the list where you want it to ap¬ 
pear. 

Like in the previous release of 
OS/2, pressing the Ctrl+Esc keys 
brings up a window with a list of 
the currently active tasks. In ver¬ 
sion 1.2, the programs in this list 
are ordered, with the programs used 
most recently shown at the top of 
the list. This makes it easier to 
switch between programs. 

DOS Compatibility 

The DOS compatibility session has 
been improved in version 1.2. Pro¬ 
grams can now be started from the 


groups of programs and from the 
File Manager; the DOS 4.00 screen 
modes with more than 25 lines are 
supported; and the amount of mem¬ 
ory required by the system in the 
lower 640 KB has been reduced, al¬ 
lowing larger DOS programs to exe¬ 
cute. 

A major enhancement is the new 
dual boot capability. It is now pos¬ 
sible to have both DOS and OS/2 in¬ 
stalled on the same fixed-disk drive. 



A major enhancement is 
the new dual hoot 
capability. 


Begin with DOS (version 3.20 or 
later) on the C: drive. All DOS 
files must be in a separate subdirec¬ 
tory. When OS/2 Version 1.2 is in¬ 
stalled, it detects the presence of the 
DOS system and implements the 
dual boot feature, which saves the 
boot record and the DOS 
CONFIG.SYS and 
AUTOEXEC.BAT files before 
OS/2 is installed. 

When changing operating systems, 
the BOOT command specifies /OS2 
or /DOS depending on which sys¬ 
tem are being activated. The boot 
record, CONFIG.SYS, and AU¬ 
TOEXEC.BAT, which were pre¬ 
viously saved, are copied to the root 
directory, and the other versions of 
OS/2 are saved. The system then re¬ 
starts itself. If this is done often, 
the BOOT command can be added 
to one of the program groups in the 
Desktop Manager. 


Remember that the dual boot fea¬ 
ture cannot be used if the High Per¬ 
formance File System (HPFS) is 
used on drive C. 

File Manager 

The File Manager, which is con¬ 
tained in the main program group, 
has been substantially improved. It 
is used to manage files and directo¬ 
ries and to execute programs. 

When it is started, the File Manager 
displays a directory map of the cur¬ 
rent drive and a pictorial mapping 
of the logical drives that are at¬ 
tached to the system. A copy of the 
File Manager can be started for 
each drive in the system. 

There is a small icon of a file folder 
next to each directory name. If 
there is a plus or minus sign in this 
icon, then this directory contains 
subdirectories. 

If the location of a file is unknown, 
select the File item in the action 
bar, then select Search in the File 
pull-down option box that is dis¬ 
played. The Search window will be 
displayed where the name of the 
file is entered. You can also spec¬ 
ify that the search can be directed to 
occur on a different drive or direc¬ 
tory, if necessary. 

Files and directories can be moved 
or copied by either dragging them 
with the mouse or by using the File 
pull-down with either the mouse or 
keyboard. Dragging the files or di¬ 
rectories with the mouse is quicker, 
but the file or directory can be re¬ 
named during the operation with the 
pull-downs. 

If files are dragged between drives, 
the files are copied. If they are 
dragged between directories on the 
same drive, they are moved. To 
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copy files to another directory on 
the same drive, hold the Ctrl key 
and press mouse button 2 while 
dragging the files. 

There are several new ways to start 
a program in version 1.2. With a di¬ 
rectory window displaying your 
data files and another open showing 
your programs, simply click on the 
data file, and drag it to the program 
file; the program will be started 
using that data file. 

If the program title is displayed in 
one of the Desktop Manager win¬ 
dows, it can be started by dragging 
the data files from the File Manager 
to its title in the Program Window 
Group. 

Programs can be associated with 
their data files. When this is done, 
double-clicking on the data file will 
start the program. If the data file 
has been associated with more than 
one program, a list of the programs 
is displayed and the program to exe¬ 
cute must be selected. 

As in the previous release, a pro¬ 
gram can be started by clicking on 
it or selecting the run option from 
the File pull-down. 

Any installed font can be used with 
the File Manager in version 1.2. It 
is often easier to see the cursor if 
you select a larger fixed-space font, 
such as one of the Courier fonts. 

This will not, however, affect the 
font used in the various dialog 
boxes. 

Printing Files 

A file can be printed in much the 
same way that a program is exe¬ 
cuted. Open a directory window 
that contains the file, select the file, 
and drag it to the Print Manager 
icon. The system will prompt to 


enter the queue or printer and the 
file will be printed. A group of 
files can be printed the same way - 
just select a group of files and drag 
them to the Print Manager. 

High Performance File 

System 

The High Performance File System 
(HPFS) is an alternate way to for¬ 
mat fixed-disk drives with OS/2 
Version 1.2. It can be installed dur¬ 
ing system installation or later with 
the FORMAT command. It sup¬ 
ports a file with either the standard 
DOS file names or long file names, 
which can be up to 255 characters 
in length. The HPFS is less perfor¬ 
mance-sensitive as files and disk 
drives increase in size. 



The High Performance 
File System supports up 
to 16 partitions on a 
drive. 


The HPFS supports up to 16 parti¬ 
tions on a drive. The partitions and 
files can be as large as 2 gigabytes. 
The HPFS is compatible with the 
File Allocation Table (FAT) system 
at the API level. This allows pro¬ 
grams written for OS/2 Versions 1.0 
and 1.1 as well as DOS programs 
running in the DOS compatiblity 
session to access HPFS files. 

No earlier version of OS/2 nor any 
version of DOS recognizes a drive 
formatted as an HPFS drive. There¬ 
fore, booting with any system other 
than OS/2 Version 1.2 will not give 
access to either the HPFS drive or 


any logical drives that are located 
after it on the same physical disk 
drive. 

For example, assume there is a sys¬ 
tem with a 120 MB fixed disk in¬ 
stalled, partitioned as drives C:, D:, 
E:, and F:. If drive C: is formatted 
as an HPFS drive and OS/2 Version 
1.2 is installed, when DOS is 
booted none of those drives can be 
accessed. 

Extended Attributes 

The version 1.2 file system supports 
extended attributes. These are user- 
defined data for a file that can be up 
to 64 KB in size. If files with ex¬ 
tended attributes are moved or cop¬ 
ied using DOS or a version of OS/2 
other than 1.2, the attributes will be 
lost. 

Long File Names 

The HPFS also supports files hav¬ 
ing names as long as 255 charac¬ 
ters. If these files are copied to a 
FAT-based drive, the names must 
be shortened. The original, long 
name is saved as an extended attri¬ 
bute of the file so that, when the 
file is copied back to an HPFS 
drive, the long name can reused. 

If the COPY or XCOPY command 
is used to copy the file to a FAT- 
based device, and there is a file 
with the short name already on that 
device, it is replaced. If the copy is 
done with the File Manager, the 
user will be asked to change the 
short name. 

System Editor 

The system editor has been en¬ 
hanced to run in a Presentation Man¬ 
ager window. It now conforms to 
the Systems Application Architec- 
ture™(SAA™) Common User Ac¬ 
cess (CUA) definition. 
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Help Manager 

The Help Manager is formally 
called the Information Presentation 
Facility or 1PF. It allows help pan¬ 
els to be developed independently 
of the flow and logic of an applica¬ 
tion program. A compiler included 
in the toolkit allows non-program¬ 
mers to create the help panels, 
which are then combined with the 
application code. The IPF can also 
provide a link between programs for 
tutorial functions. The IPF can be 
used by both Presentation Manager 
and Dialog Manager applications. 
The IPF complies with the SAA 
CUA requirements. 

Miscellaneous Improvements 

Three new utilities work with pic¬ 
ture files. PICPRINT allows the 
user to print metafiles and Picture 
Interchange Format (PIF) files. PIC- 
SHOW displays picture files on the 
screen. PICICHG converts PIF 
files into metafiles. 

The Presentation Manager now has 
API calls that provide support for 
the help system and support for 
both FORTRAN and COBOL. 

New device drivers are included 
with the system. A PostScript™ 
driver is provided for the IBM Page 


Printer II models 4216-030 and - 
031, and other PostScript printers. 

A driver is also provided for the 
Epson™ FS80 (9-wire) and LQ1500 
(24-wire) printers. 

FDISK now runs under the Presenta¬ 
tion Manager. It displays all infor¬ 
mation about a fixed disk on one 
screen, making it much easier to use. 



A compiler included in 
the toolkit allows 
non-programmers to 
create the help panels. 


The system can now support 64,000 
file handles, and a single process 
can access 32,000 file handles. 

The FORMAT command has been 
changed to make it easier to remem¬ 
ber its parameters. For example, to 
format a 720 KB diskette in a 1.44 
MB drive, the command is “FOR¬ 
MAT A: /F:720KB”. Of course, if 
the user still forgets the syntax, en¬ 
tering the command “HELP FOR¬ 


MAT” on the command line will ac¬ 
tivate the online command reference 
and display a description of the com¬ 
mand and its parameters. 

The quick reference card has a com¬ 
plete mapping of the Desktop Man¬ 
ager functions. The reverse side 
describes how the keys are used by 
each of these function. 
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An Application 
Developer’s 
View of OS/2 

Peter Kron 
Aldus™ Corporation 
Seattle, Washington 

In this article Aldus shares their 
experiences in developing 
PageMaker® for OS/2 Presenta¬ 
tion Manager. The article points 
out the OS/2 features the develop¬ 
ers used to their advantage, and 
potential pitfalls that are not nec¬ 
essarily endemic to the operating 
system itself, but which can trip 
up an OS/2 developer who is ac¬ 
customed to developing applica¬ 
tions for Windows™ or the 
Macintosh®. 

Aldus Corporation began shipping 
PageMaker for OS/2 Presentation 
Manager in September 1989, com¬ 
pleting a process that had begun 
more than two years before, when 
the first OS/2 developer conferences 
were held. During this period, 

Aldus engineers worked closely 
with Microsoft and had access to nu¬ 
merous pre-release software devel¬ 
opment kits (SDKs). 

Concurrent with this development 
effort, major new releases of the 
Macintosh and Windows versions 
of PageMaker were developed and 
released, providing a unique van¬ 
tage point for assessing OS/2 as a 
development environment. 

Background 

The process of creating PageMaker 
for OS/2 benefited greatly from our 
experiences with the Windows and 
Macintosh versions of PageMaker. 
The existence of two versions had 
forced PageMaker to straddle the 
host application program interface 


(API) fence successfully for almost 
three years. A key element of that 
success has been the core/edge code 
concept - between 50 and 75 per¬ 
cent of PageMaker is shared by 
those two platforms. (PageMaker is 
written almost entirely in C.) 

Because OS/2 and Windows share 
common hardware and software an¬ 
cestry, OS/2 became more of a sub¬ 
division of the Windows edge than 
an entirely new, third edge. Our ex¬ 
perience with Windows was cer¬ 
tainly a great advantage in writing 
for OS/2 Presentation Manager (al¬ 
though in some instances we as¬ 
sumed similarities that were not 
true). 

Our goal was to use as much core 
and Windows edge code as possi¬ 
ble, preserving the “look and feel” 
of PageMaker and file compatibil¬ 
ity. But we also wanted to take ad¬ 
vantage of inherent features of OS/2 
to improve productivity wherever 
possible. 

OS/2 Presentation Manager 

OS/2 Presentation Manager is really 
a mixture of two levels of API: Win¬ 
dow Management and Graphics Im¬ 
aging. They reflect dual parentage 
by Microsoft and IBM. Window 


Management is very similar to the 
Windows API, while Graphics Imag¬ 
ing bears strong resemblance to 
IBM mainframe graphics models. 

Similarly, our code base has a win¬ 
dow management edge (front end) 
and an imaging edge (back end) 
(Figure 1). The various core func¬ 
tions, such as data storage and text 
composition, fit generally in the 
middle. Because we had an estab¬ 
lished Windows edge for the front- 
end, we were able to modify it to 
handle the OS/2 API. One of the 
most common API differences is 
the addition of an “anchor block” 
handle to Presentation Manager 
calls; the Windows equivalents have 
no such argument. Changes of this 
nature could be dealt with by com¬ 
piler macros. Other differences are 
limited to argument types and con¬ 
stants, and could be resolved by con¬ 
ditional datatype definitions. 

Nonetheless, there are subtle differ¬ 
ences that can trip up a developer. 
One of the most pervasive is the 
switch from a top-left-based origin 
in Windows to a bottom-left origin 
in Presentation Manager (Figure 2). 
This bias affects relative placement 
of child windows (such as rulers), 
common drawing code, and genera- 


Windows 

OS/2 

Macintosh 

Core 

Windows 

OS/2 

Macintosh 


Event 

Messages 


Imaging 


Figure 1. Code Structure 
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tion of bitmap images. The compu¬ 
tation needed to convert from one 
form to the other is dependent upon 
current window height. While this 
computation is not difficult, it af¬ 
fects a surprising amount of code 
and will be the source of many bugs 
if not anticipated adequately. 

For example, Aldus had isolated 
many differences between Windows 
and Macintosh in their respective 
“edges.” If core code contained as¬ 
sumptions specific to one or the 
other, the problem soon became ap¬ 
parent during testing. But because 
both followed a top-left imaging 
model, dependencies on this orienta¬ 
tion went unnoticed in the core 
code and subsequently caused vari¬ 
ous problems in porting to OS/2. 

A second subtlety is that some of 
the windowing messages differ only 
slightly from each other, either in in¬ 
terpretation, parameters, or order of 
generation. These slight differences 
are more bothersome than outright 
new messages, which can be condi¬ 
tionally handled. For example, sub¬ 


tle changes in the interpretation of 
keystroke messages from Windows 
to OS/2 changed the basic assump¬ 
tions of the routines - again requir¬ 
ing changes to a large amount of 
code spread throughout the pro¬ 
gram. The Presentation Manager 
scheme is in many respects an im¬ 
provement, but just the difference 
can be bothersome. There is also a 
particular problem when dealing 
with stable, familiar code that has 
been ported to a new environment; 
sometimes the engineer is still think¬ 
ing in terms of the previous environ¬ 
ment, and subtle differences can be 
a real blind spot. 

Imaging Models 

The imaging model of Presentation 
Manager differs radically from that 
of Windows, causing the macros to 
be ineffective as a porting tool. It 
was possible to use conditional code 
for the imaging because the imaging 
code was already fairly well modu¬ 
larized at the back end of the appli¬ 
cation. Certain edge-specific 
modules required complete rewrit¬ 
ing, however. (Conditional code 


was used primarily in modules that 
were already Windows-specific.) In 
a few key instances, we were able 
to take advantage of the opportunity 
to improve our core-edge boundary 
by defining new platform-indepen¬ 
dent service routines and bundling 
the OS/2-specific code there. Our 
main guideline was readability: if a 
specific section could be written as 
conditional code without too much 
loss of readability, we didn’t feel it 
was necessary to define new service 
routines at that time. 

A more difficult imaging problem 
was resolving the pixel-specific idio¬ 
syncrasies of the two graphics mod¬ 
els. While both models are based 
on stroking path lines of a defined 
width, the two imaging engines do 
not always end up with the same 
pixels being affected. It took some 
work to get the algorithms recoded 
so that PageMaker graphics and text 
would butt up properly under Pre¬ 
sentation Manager. 

Displaying text is an extreme exam¬ 
ple of this problem, due to the com¬ 
plexity of the metrics associated 
with text fonts. In addition, because 
the representation of font names and 
attributes is significantly different 
under the Macintosh, Windows and 
Presentation Manager environments, 
font code had to be rewritten from 
scratch. Font technology in general 
has been a hot topic recently, and 
there will undoubtedly be more 
changes in these areas. The good 
news from all of this is that font is¬ 
sues are being studied more seri¬ 
ously than ever, and solutions are 
being found. 

Solutions to all of these problems 
have to address four basic device 
types: 1:1 screen aspect ratios 
(such as VGA), other screen aspect 
ratios (such as EGA), PostScript 
printers, and raster printers. No im- 
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aging model is perfectly device-in¬ 
dependent, so the way in which the 
application uses the engine API can 
be very sensitive to the particular 
constraints imposed by both applica¬ 
tion requirements and the capabili¬ 
ties of the device (such as resolution 
and resident fonts). 

There are several areas of technical 
difference in the two APIs. Presen¬ 
tation Manager’s Graphics Program¬ 
ming Interface (GPI) has a much 
richer set of capabilities than Win¬ 
dows, including new curve primi¬ 
tives, pick-correlation of mouse 
actions, line attributes versus pen ob¬ 
jects, and redraw of complex ob¬ 
jects by the engine itself. The GPI 
also provides a (somewhat daunt¬ 
ing) hierarchy of viewing trans¬ 
forms. For an application, such as 
PageMaker, which is to be available 
on other platforms without these fea¬ 
tures, it is a difficult task to take 
full advantage of these features 
while hiding the platform-specific 
implementations. This is an area 
we are still refining. 

A final note of caution: the Win¬ 
dows Device Context is split into 
two handles under OS/2 Presenta¬ 
tion Manager. Some analogs to the 
Windows API require the Presenta¬ 
tion Manager Device Context, while 
others require the Presentation 
Space. Presentation Manager can 
also associate multiple Presentation 
Spaces with a Device Context, and 
fonts are associated with the Presen¬ 
tation Space. The result can be 
changes to some function-interface 
definitions to provide each function 
with the proper handle. 

Developing Applications in 
OS/2 

The four main features of OS/2 that 
affect development decisions are 
more memory, enriched graphics, 


multitasking, and multithreading. 
PageMaker does not currently uti¬ 
lize many of the graphic extensions 
provided by the GPI, but I will dis¬ 
cuss what each of the other features 
brings to PageMaker for OS/2. 



PageMaker for OS/2 uses 
multithreading, which is 
quite effective in 
improving the 
responsiveness of the 
application. 

The larger address space reduces 
code swapping in PageMaker, result¬ 
ing in an immediate boost in raw 
performance. This is about as close 
to a free lunch as can be found in 
the software business. In the design 
phase, we discussed various 
changes to our caching algorithms, 
based on the assumption of having 
more memory, but we implemented 
only some basic caching of bitmaps 
and font metrics. There is still lots 
of room for enhancements in this 
area - such as in tuning file manage¬ 
ment - but we didn’t feel that the 
gains would be significant enough 
to mandate their inclusion in this re¬ 
vision. 

PageMaker for OS/2 opens multiple 
publications, a feature, which is 
unique to this platform. Cutting 
and pasting between publications is 
consequently simpler for the user 
than in Windows. This feature was 
implemented by creating a separate 
process for each publication win¬ 
dow. Multitasking - using separate 
processes - facilitates background 
operations such as flowing text and 


printing. While this feature does 
not alter the raw performance of the 
application, it has a dramatic effect 
on the productivity of users, by free¬ 
ing them to work in other areas 
while the operation completes. 

Achieving the same level of inde¬ 
pendent activity by implementing 
threads within one process would 
have required considerable synchro¬ 
nization of access to data structures. 
Using multiple processes is much 
more straightforward. There is 
some overhead in this approach, be¬ 
cause cursor and other resources 
must be loaded separately; but be¬ 
cause the code itself is all shared, 
using separate processes was our 
preferred choice. PageMaker cre¬ 
ates shared memory - another OS/2 
feature - which is used by the differ¬ 
ent processes to coordinate this ac¬ 
tivity. 

PageMaker for OS/2 does use multi¬ 
threading as well, which is quite ef¬ 
fective in improving the 
responsiveness of the application. 
Three threads are always active - a 
message thread, a service thread, 
and a paint thread (see Figure 3). A 
separate message thread is needed 
to ensure that all input messages are 
handled quickly, because this is es¬ 
sential to overall Presentation Man¬ 
ager performance. Calling a 
subroutine to print a page while pro¬ 
cessing the PRINT command mes¬ 
sage would prevent Presentation 
Manager from dispatching any fur¬ 
ther messages to any applications, 
and so the hourglass would linger. 
Presentation Manager guidelines 
state that no message should require 
more than one-tenth of a second pro¬ 
cessing. To meet this guideline, 
long user operations in PageMaker - 
printing, importing data, and flow¬ 
ing text - are performed by the 
service thread. The message thread 
waits for another message, thus al- 
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lowing Presentation Manager to acti¬ 
vate other applications. Program ini¬ 
tialization is also done largely by 
the service thread, absorbing the 
idle time while the user invokes the 
NEW or OPEN dialog. 

This synchronization is compli¬ 
cated, because the user may con¬ 
tinue typing or mouse activity, 
which resumes the message thread 
while the service thread is still ac¬ 
tive. In this instance, PageMaker 
for OS/2 Presentation Manager fil¬ 
ters these messages and only ac¬ 
cepts certain basic ones, such as 
RESIZE and MINIMIZE. A private 
message is posted from the service 
thread to indicate completion of its 
task. Since user activity in this pro¬ 
cess is restricted, we give the user 
feedback by disabling menu items 
and displaying a “busy” cursor, 
which is distinct from the hourglass. 
This cursor will change when 
moved to other windows (because 
the user is free to switch to other ap¬ 
plications), but the hourglass will 
not. In future versions we hope to 
handle a greater variety of messages 
while service threads are active. 

Screen redraw is performed by a 
separate paint thread in PageMaker. 


There are two reasons for this: 
first, since PageMaker does not 
limit the number of objects appear¬ 
ing on a page, redraw can easily ex¬ 
ceed the guideline of one-tenth of a 
second to process events. More im¬ 
portantly, using a separate thread al¬ 
lows a greater responsiveness to the 
user by allowing the redraw to be 
aborted. If a newly opened page is 
at the wrong view, the resize com¬ 
mand can take effect immediately 
rather than completely redrawing 
the page, resizing and completely re¬ 
drawing again. Dynamic scrolling - 
redrawing the screen as the user 
drags the scroll thumb - also oc¬ 
curs, because monitoring the scroll 
bar is handled by the message 
thread. (The rulers are also drawn 
by the message thread, because that 
is fast and gives immediate posi¬ 
tional feedback to the user. The 
page redraw constantly tries to 
catch up.) Users greatly appreciate 
this new responsiveness. 

While dynamic redraw can be imple¬ 
mented without multithreading, it 
places a much greater burden on the 
application developer to poll for pos¬ 
sible messages at various points. 
Multithreading allows the concur¬ 
rent activities to be separated more 


naturally in the code. The GPI en¬ 
gine itself anticipates the user multi¬ 
threading and performs some of the 
necessary synchronization for the 
application, further simplifying the 
engineer’s task. 

Assessing the OS/2 
Development Environment 

In the early SDKs, it was advised 
that development be done under 
DOS and that OS/2 be used only for 
testing. As the SDKs matured, how¬ 
ever, it became more advantageous 
to work in OS/2 entirely. Now we 
have come full circle - developing 
for Windows on OS/2, and reboot¬ 
ing to DOS for testing. 

One of the first things developers 
get very accustomed to in OS/2 is 
having multiple command sessions. 
This is not only useful for doing 
background or simultaneous com¬ 
piles, but also for preserving your 
current state. I find it very comfort¬ 
able to quickly switch from one 
screen to another just to work in an¬ 
other directory with a new set of en¬ 
vironment variables. Another 
advantage is being able to keep 
your train of thought while the com¬ 
pile takes place. Under DOS, it is 
common to juggle a mental list of 
minor editing changes to make once 
the compile completes - and not un¬ 
common to lose time if something 
is forgotten. 

The next thing to notice is that the 
dreaded “out of heap” message dis¬ 
appears from the C compiler. All 
the development tools run in pro¬ 
tected mode, and therefore have ac¬ 
cess to considerably more memory 
for internal table storage. No 
longer is the developer interrupted 
by the need to break up modules ar¬ 
tificially just to get them to com¬ 
pile. Linking a large application, 
especially when containing debug 
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code and debugger data, is an order 
of magnitude faster with OS/2 mem¬ 
ory management than with using vir¬ 
tual-disk scratch files under DOS. 

Debugging in OS/2, using 
CodeView®, Logitech’s™ Multi¬ 
scope™ or one of the other avail¬ 
able debuggers, is much easier than 
in either Windows or the Macin¬ 
tosh, although it is not without defi¬ 
ciencies (such as being unable to 
interrupt a looping application). 
Source-level debugging with these 
tools is a great improvement over 
glass-TTY tools such as Windows 
SYMDEB. In addition, because of 
OS/2 multitasking the debugging 
tools intrude less on the target appli¬ 
cation. (PageMaker was never able 
to use CodeView in practice on 
Windows - 640 KB was just too 
small.) 

QuickHelp (in the SDK) is also 
very effective in this environment. 

I frequently leave a QuickHelp win¬ 
dow on the screen for reference 
while editing source code. It gener¬ 
ally provides thorough coverage of 
the parameters and options available 
for any system call, eliminating the 
need to shuffle through the sizable 
manuals. The engineer can have 
the application, debugger, source 
files and reference manual all 
within a few keystrokes. These 
things do require memory, though: 
our development was done on 4 
MB machines, but that is the bare 
minimum. 6 MB prevents a lot of 
swapping activity. 


Last but not least, a protected mem¬ 
ory environment is a great time- 
saver during development, just to 
isolate dumb mistakes and uni¬ 
nitialized pointers. Some poten¬ 
tially nasty bugs - the Ctrl-Alt-Del 
kind on Windows - have become 
trivial to find and fix when the hard¬ 
ware gives you a helping hand. 



OS/2’s architecture lays 
the groundwork for much 
tighter coordination 
among different tasks on 
a user’s desktop. 


So what are the problems with OS/2 
development? For one thing, your 
favorite TSRs and tools still may 
not be there. Many tools will run in 
the DOS compatibility box, but can¬ 
not be invoked from protected- 
mode command files yet. The same 
may be true of various hardware or 
network options. You may have to 
reboot DOS until the driver support 
is there. Finally, Presentation Man¬ 
ager is robust about announcing er¬ 
rors, but finding the errors 
themselves can sometimes be te¬ 
dious. There is room for a lot more 
diagnostic tools to help clean and 
tune the code. But on the whole, 
OS/2 is well worth investigation as 
a development environment. 


Potential 

PageMaker for OS/2 has been recog¬ 
nized in the press for making some 
of the benefits of OS/2 real to the 
end user. OS/2’s architecture lays 
the groundwork for much tighter co¬ 
ordination among different tasks on 
a user’s desktop. Some will be in¬ 
voked by explicit user action or re¬ 
sult from links between documents; 
some will result from background 
service tasks that are not visible to 
the average user except in the form 
of enhanced productivity. Network¬ 
ing, too, will take place at various 
levels of user visibility. As more 
applications like PageMaker be¬ 
come available on OS/2, a critical 
application mass will be reached, 
and this potential will be tapped. 


ABOUT THE AUTHOR 

Peter Kron, a principal software 
engineer at Aldus Corporation, was 
the technical lead in development of 
Aldus PageMaker for OS/2. He 
also worked on both the Windows 
and Macintosh versions of Aldus 
PageMaker. Peter received a 
degree in mathematics from 
Dartmouth College. Since then, he 
has worked extensively in the 
development of database software 
and publishing workstations. 

Aldus Corporation 

411 First Ave. South, Suite 200 

Seattle, Washington 98104 


Personal Systems/Issue 2, 1990 



18 


Object-Oriented 
Programming 
with C and 
OS/2 PM - 
Is It Possible? 

Hans J. Eisenhuth 
SE International , Inc. 

Boca Raton , Florida 

This article aims to prove that ob¬ 
ject-oriented programming with 
OS/2 Presentation Manager (PM) 
and C is possible, even though C 
is not an object-oriented program¬ 
ming language. It also shows 
that object-oriented design and 
the right programming techniques 
have more influence on the object- 
orientedness of an application 
than the object-orientedness of 
the programming language itself. 

The discussion about object-ori¬ 
ented programming (OOP) has in¬ 
creased dramatically with the 
introduction of OS/2 Presentation 
Manager and object-oriented pro¬ 
gramming languages such as C++®, 
Ada and Smalltalk. 

Whenever you talk about the advan¬ 
tages of Presentation Manager as a 
base for software development you 


come across statements such as: 

• You can only write object- 
oriented applications with a true 
object-oriented programming lan¬ 
guage like Smalltalk or C++. 

• C is not an object-oriented pro¬ 
gramming language. Therefore 
PM applications written in C can¬ 
not be object-oriented. 

These statements are also used as an 
excuse for the fact that the first ap¬ 
plication developed with C and PM 
does not show the expected object- 
orientedness results. 

We will analyze these statements 
and find out whether they are justi¬ 
fied. At the end we will see that ob¬ 
ject-oriented programming is 
achievable with C and PM. We just 
have to adapt our problem-solving 
techniques and change our way of 
thinking a bit. 

Criteria for 
Object-Orientedness 

Most of the literature about OOP 
briefly discusses the fundamentals 
before starting a detailed discussion 
of object-oriented programming 
based on an OOP programming lan¬ 
guage. The reader might therefore 
come to the conclusion that only 



real OOP languages allow object- 
oriented programming. 

An exception to the rule is Bertrand 
Meyer’s book Object-Oriented Soft¬ 
ware Construction (Prentice Hall, 
pages 60-63), in which he lists the 
“7 steps toward object-based happi¬ 
ness.” These steps are criteria for de¬ 
termining the object-orientedness of 
an application. 

These criteria will be used to check 
whether OS/2 applications written 
in C can be object-oriented. 

Object-Based Modularization: To 

achieve true object-orientedness, ap¬ 
plications must be modularized on 
the basis of their data structures. 
However, the majority of applica¬ 
tion designers and developers still 
use the data flow-oriented design 
principles - that’s why we still see 
so many flowcharts. This approach 
does not lead to an object-oriented 
design and therefore not to an ob¬ 
ject-oriented application. 

Modem software engineering dis¬ 
tinguishes between three design 
principles: 

• Data flow-oriented design (DFD) 

• Data structure-oriented design 
(DSD) 

• Object-oriented design (OOD) 

These design principles are used to 
determine the modules (highly inde¬ 
pendent program entities) of an ap¬ 
plication. 

The data flow-oriented design is 
based on a “top-down” design tech¬ 
nique, whereas the data structure- 
oriented design is based on a “bot¬ 
tom-up” design technique. The ob¬ 
ject-oriented design, as the newest 
principle, combines the techniques 
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of DFD and DSD to a “Yo-Yo”(top- 
down / bottom-up) technique. The 
different design principles are dis¬ 
cussed extensively by Roger S. 
Pressman in his book Software Engi¬ 
neering - A Practitioner 9 s Ap¬ 
proach (McGraw-Hill). 

Only the object-oriented design ap¬ 
proach will lead to an object-ori¬ 
ented application with all its 
advantages. If we have a proper ob¬ 
ject-oriented oriented design we can 
implement systems with PM and C 
and get object-oriented applications, 
even though C is not an object-ori¬ 
ented language. 

Abstract Data Types: Truly object- 
oriented applications allow the defi¬ 
nition and use of abstract data types. 

An abstract data type is specified as 
a list of services which allow the 
use and modification of data struc¬ 
tures. These services are operations 
or features that allow the external 
view of objects without disclosing 
the internally used data structures. 

The book, Einfiihrung in Software 
Engineering (sorry, it’s a book writ¬ 
ten in German) uses abstract data 
types to: 

• Isolate important data structures 
from their usage 

• Define prototypes of common 
data structures together with their 
access routines 

Figure 1 shows how an abstract 
data type hides the data structures 
through an interface of access rou¬ 
tines. 

To implement abstract data types, a 
modern programming language 
must provide the following: 

• Definition of abstract data types 


• Creation of objects of an abstract 
data type 

• Manipulation of an object exclu¬ 
sively through the use of services 
defined in the abstract data type 

• Side-effect-free use of data 

In Presentation Manager, an abstract 
data type is equal to a window 
class, and a window is equivalent to 
an object. The PM function 
WinRegisterClass defines a win¬ 
dow class, and WinCreateWindow 
creates a window of a given win¬ 
dow class. 

Sending or posting a message to a 
window is equal to a service re¬ 
quest. The window procedure of a 
window class determines how all ob¬ 
jects of a class have to respond to 
service requests. That means the 
window procedure defines the be¬ 
havior of all windows of a window 
class. 

A good programming technique to 
hide the PM-specific parameters 
and functions for the creation of an 
object is to provide an object cre¬ 


ation function for each window 
class. This should perform the class 
registration and object creation. 

The parameter list for the creation 
function must contain only applica¬ 
tion specific parameters. Figure 2 
shows the layout of an object cre¬ 
ation function. 

A key requirement for abstract data 
types is that their description and 
implementation is absolutely free of 
side effects. A side effect occurs 
when an object uses or manipulates 
data that has been defined outside 
of the object’s scope. 

It is obvious that the exclusive use 
of instance variables in an applica¬ 
tion (be it object-oriented or not) re¬ 
duces the maintenance effort 
dramatically. This requirement is 
automatically implemented in real 
OOP languages. In a PM/C applica¬ 
tion we have to use proper program¬ 
ming techniques to fulfill this 
requirement. We have to make sure 
that a window does not use any 
global variables or variables defined 
outside of its window procedure. 

The window data (or better called 
instance data) should be stored or 
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Figure 1. Abstract Data Types: Access routines hide the internal data structure 
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maintained with the help of window 
words. 

OS/2 and C provide a wide (some 
people say, too wide) variety of 
memory management functions and 
good support for maintaining these 
window words. But application de¬ 


velopers and designers have not 
taken enough notice of this tech¬ 
nique so far. Figure 3 shows how 
an object-oriented window proce¬ 
dure should look. 

If we use only properly imple¬ 
mented instance data and use only 


PM’s message-passing philosophy 
to modify the instance data, we are 
able to implement abstract data 
types in a PM application written in 
C (PM/C). 

Automatic Memory Management: 

For the purpose of de-allocating un- 


HWND CreateObject ( Input Parameters) 

{ 

WinRegisterClass (.) ; 

Error code checking; 


Prepare the input parameters so that 
properly to the new window object as 

they can be passed 
a control parameter; 

hwndObject = WinCreateWindow (...., control parameter,.); 
error code checking; 

return (hwndObject) ; 

} 



Figure 2. Object Creation Function: Used to hide complex PM functions 


INT EXPENTRY WinProc (HWND hwnd, USHORT msg, LPARAM1 lpl, LPARAM2 lp2) { 

typedef struct__INSTANCE { 

USHORT usNumber; 

. . . . /* Further instance data */ 

}INSTANCE; 

INSTANCE *plnstance; /* Pointer to window's instance data */ 

switch (msg) 

case WM_CREATE: 

Allocate space for the instance data; 

Initialize the instance data; 

Store the pointer plnstance in a window word; 

Do further initialization- 
break; 

case WM_XXX: 

Retrieve plnstance from the window word; 

Perform the WM_XXX related behavior; 
break; 


case WM_DESTROY: 

Retrieve plnstance from the window word; 

Free the memory to which plnstance points; 
break; 

default: 

return (WinDefWindowProc (hwnd, msg, lpl, lp2)) ; 

} 

return (0L); 

}/*END of WinProc*/ 


Figure 3. Use of Instance Data 
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used objects, real object-oriented 
languages provide the function of a 
garbage collector, which browses pe¬ 
riodically through the application’s 
bound memory resources and frees 
unreferenced portions of memory. 

As we have seen in the previous 
chapter, management of instance 
data for an object must be done 
“manually” in its window proce¬ 
dure. In the implementation of a 
window procedure we have to en¬ 
sure that the instance data of a win¬ 
dow is freed when the 
WM_DESTROY message is re¬ 
ceived by an object (Figure 3). 

However, the hierarchical window 
structure in Presentation Manager 
makes sure that all dependent win¬ 
dows are destroyed whenever the 
parent window is destroyed. No 
programmer intervention is neces¬ 
sary. 

Classes: A class is the implementa¬ 
tion of an abstract data type in a 
highly independent and coherent 
fashion. To ensure this indepen¬ 
dence, the application must be mod¬ 
ularized so that each module is 
equal to the implementation of an 
abstract data type. 

Because C does not provide a na¬ 
tive support for independent classes, 
we have to ensure independence 
through the usage of good program¬ 
ming techniques. 

Let us have a look at PM’s pre¬ 
defined system classes, such as 
classes for list boxes, entry fields or 
standard windows. The code for 
these window classes is held in sepa¬ 
rate Dynamic Link Libraries 
(DLLs). DLLs are perfectly suited 
to hold an independent implementa¬ 
tion of an abstract data type. There¬ 
fore, we should also use this 
technique for application-specific 


classes. 

Each Dynamic Link Library should 
contain: 

• The window procedure(s) 

• Related functions (such as the ob¬ 
ject creation function) 

• All privately used functions 

• The related PM resource defini¬ 
tions 

This technique enforces class auton¬ 
omy and data usage without side ef¬ 
fects. Modification of a class which 
is held in a DLL is highly transpar¬ 
ent for other applications that use 
objects of this class. Applications 
(or other classes) don’t have to be 
recompiled or relinked, because the 
code of the modified window class 
is linked dynamically during run¬ 
time. 

Presentation Manager also allows 
the creation of public new system 
window classes. This means that 


new window classes are registered 
at system start and applications no 
longer care about registering new 
classes. 

But don’t forget: to use this feature 
of OS/2 efficiently, you must have 
designed your application(s) in an 
object-oriented fashion. 

Inheritance: Inheritance is a key 
issue in object-oriented program¬ 
ming. It leads to high code re¬ 
usability and easier maintenance, be¬ 
cause it allows the definition of a 
new class as an extension or restric¬ 
tion of an already existing class. 
Only the modified behavior must be 
described in the new class, while 
the unchanged behavior is inherited. 

The implementation of inheritance 
in a PM/C application is based on 
subclassing. The subclassing tech¬ 
nique allows extension or restriction 
of an object’s functionality simply 
by intercepting the message flow to 
the object. Be aware that this tech¬ 
nique changes the behavior of an ob¬ 
ject, but not of a class. The classic 


WinSubClassWindow (hwnd, EntryWP); 
Presentation Manager 

Entry WP 


SubProc 


Figure 4. Message Flow to a Subclassed Window Procedure 
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example for subclassing is the im¬ 
plementation of a numeric entry 
field, which inherits the behavior of 
an unrestricted entry field (Figure 4). 

The WinSubClassWindow func¬ 
tion tells PM that all messages to a 
specific window (hwnd) should be 
passed first to an application-spe¬ 
cific procedure (SubProc). SubProc 
analyzes all messages before it 
passes them to the “real” window 
procedure (EntryWP). The 
functionality of the entry field can 
now be extended, for example, by 
displaying a message if the user 
presses an alphabetic key, or re¬ 
stricted, for example, by filtering al¬ 
phabetic WM_CHAR messages. 

SubProc has the same structure as a 
window procedure. Therefore, we 
can create a new window class of 
numeric entry fields by creating a 
public window class with SubProc 
as a window procedure. Figure 5 
shows the layout of the numeric 
entry field window procedure Sub¬ 
Proc. Notice that SubProc calls 
Entry WP instead of the Window de¬ 
fault procedure. This actually imple¬ 
ments the inheritance in PM 
window classes. 

Polymorphism: Polymorphism en¬ 
ables objects of different classes to 


respond to the same service request. 
A program entity requesting a ser¬ 
vice from an object doesn’t care 
which class the object belongs to. 

It just issues the request. Of course, 
it is necessary that the class behav¬ 
ior is prepared to service the request 
in a commonly agreed manner, but 
the implementation may vary from 
class to class. 



It is possible to develop 
fully object-oriented 
applications with C 
under the control of OS/2 
Presentation Manager. 


A Presentation Manager example is 
the message WM_PAINT. Any 
window of any class should repaint 
itself when it receives the 
WM_PAINT message. Presentation 
Manager just sends this message to 
all windows that have to be updated 
without worrying about the imple¬ 
mentation of repainting in certain 
windows. 


To allow polymorphism in a PM in¬ 
formation system, we should define 
a range of message identifiers 
which are reserved system-wide for 
polymorphic use. Whenever a new 
class is developed, the development 
team has to ensure that the window 
procedure of this new class re¬ 
sponds correctly to these polymor¬ 
phic messages. 

Multiple and Repeated 
Inheritance: This criterion of ob¬ 
ject-orientedness is just an exten¬ 
sion of the previously discussed 
inheritance criterion. It allows an 
object to have more than one par¬ 
ent, from whom it inherits 
functionalities. This is a very spe¬ 
cific requirement for an OOP lan¬ 
guage; however, it should be 
mentioned here for completeness. 

In real OOP languages this require¬ 
ment makes special language con¬ 
structs necessary. Presentation 
Manager and C do not provide spe¬ 
cial language constructs for inheri¬ 
tance. The entire PM/C program 
processing is based on sending and 
receiving messages. This basic tech¬ 
nique allows the definition of object 
classes with more than one parent. 


MRESULT EXPENTRY SubProc (HWND hwnd, USHORT msg, LPARAM lpl, LPARAM lp2){ 

Query original entry field WP EntryWP 

switch (msg){ 
case WM_CHAR: 

if character is alphabetic 

{Display error message or beep 
Return (0) } 

break; 

} /* end switch */ 

return (EntryWP (hwnd, msg, lpl, lp2)); 

} /* End SubProc */ 


Figure 5. Subclass Window Procedure: Window procedure for numeric entry field class 
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Conclusion 

Having examined the different cri¬ 
teria of object-orientedness, we can 
say that it is possible to develop 
fully object-oriented applications 
with C under the control of OS/2 
Presentation Manager. 

Contrary to the PM/C environment, 
real OOP languages provide lan¬ 
guage constructs that enforce object- 
oriented programming. These 
language constructs allow for more 
comfortable creation and structuring 
of classes, objects and instance data. 
They also check the correct use of 
objects at compilation time, which 
facilitates program debugging. 
Therefore, object-oriented program¬ 
ming becomes more obvious in lan¬ 
guages like Smalltalk or C++. 

The advantage of C and Presenta¬ 
tion Manager is their conformance 
to SAA. It assures compatibility 


with current and future components 
of the SAA architecture and pro¬ 
tects your hardware, software and 
programmer education investments. 

Irrespective of the language you use 
for implementing an object-oriented 
application, it is much more impor¬ 
tant to apply the right object- 
oriented design methodology. If 
you have not designed your applica¬ 
tion in an object-oriented fashion, 
you will not successively implement 
an object-oriented application, even 
if you use a real OOP language. 

If an application has been designed 
to be object-oriented, you will find 
that OS/2 Presentation Manager and 
C provide excellent capabilities to 
implement multitasking and 
SAA/CUA conforming applications 
in a cooperative processing environ¬ 
ment. And that’s where we want to 
go! 
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The High Performance File Sys¬ 
tem (HPFS), which is making its 
first appearance in the OS/2 Ver¬ 
sion 1.2 operating system, had its 
genesis in the network division of 
Microsoft and was designed by 
Gordon Letwin, the chief architect 
of the OS/2 operating system. 

The HPFS has been designed to 
meet the demands of increasingly 
powerful PCs, fixed disks, and net¬ 
works for many years to come 
and to serve as a suitable plat¬ 
form for object-oriented lan¬ 
guages, applications, and user 
interfaces. 

The HPFS is a complex topic be¬ 
cause it incorporates three distinct 
yet interrelated file system issues. 
First, the HPFS is a way of organiz¬ 
ing data on a random access block 
storage device. Second, it is a soft¬ 
ware module that translates file-ori¬ 
ented requests from an application 
program into more primitive re¬ 
quests that a device driver can un¬ 
derstand, using a variety of creative 
techniques to maximize perfor¬ 
mance. Third, the HPFS is a practi¬ 
cal illustration of an important new 


OS/2 feature known as installable 
file systems. 

This article introduces the three as¬ 
pects of the HPFS. But first, it puts 
the HPFS in perspective by review¬ 
ing some of the problems that led to 
the system’s existence. 

FAT File System 

The so-called FAT file system, 
which is the file system used in all 
versions of the MS-DOS® operat¬ 
ing system to date and in the first 
two releases of OS/2 (see Note 1) 
Versions 1.0 and 1.1, has a dual her¬ 
itage in Microsoft’s earliest pro¬ 
gramming language products and 
the Digital Research® CP/M® oper¬ 
ating system - software originally 
written for 8080-based and Z-80- 
based microcomputers. It inherited 
characteristics from both ancestors 
that have progressively turned into 
handicaps in this new era of multi¬ 
tasking, protected mode, virtual 
memory, and huge fixed disks. 

The FAT file system revolves 
around the File Allocation Table for 
which it is named. Each logical vol¬ 
ume has its own FAT, which serves 
two important functions: it contains 
the allocation information for each 
file on the volume in the form of 
linked lists of allocation units (clus¬ 
ters, which are power-of-2 multiples 
of sectors) and it indicates which al¬ 
location units are free for assign¬ 
ment to a file that is being created 
or extended. 

The FAT was invented by Bill 
Gates and Marc McDonald in 1977 
as a method of managing disk space 
in the NCR version of stand-alone 
Microsoft® Disk BASIC. Tim 
Paterson, at that time an employee 
of Seattle Computer Products 
(SCP), was introduced to the FAT 
concept when his company shared a 


booth with Microsoft at the Na¬ 
tional Computer Conference in 
1979. Paterson subsequently incor¬ 
porated FATs into the file system of 
86-DOS, an operating system for 
SCP’s S-100 bus 8086 CPU boards. 
86-DOS was eventually purchased 
by Microsoft and became the start¬ 
ing point for MS-DOS (see Note 2) 
Version 1.0, which was released for 
the original IBM PC in August 
1981. 

When the FAT was conceived, it 
was an excellent solution to disk 
management, mainly because the 
floppy disks on which it was used 
were rarely larger than 1 MB. On 
such disks, the FAT was small 
enough to be held in memory at all 
times, allowing very fast random ac¬ 
cess to any part of any file. This 
proved far superior to the CP/M 
method of tracking disk space, in 
which the information about the sec¬ 
tors assigned to a file might be 
spread across many directory en¬ 
tries, which were in turn scattered 
randomly throughout the disk direc¬ 
tory. 

When applied to fixed disks, how¬ 
ever, the FAT began to look more 
like a bug than a feature. It became 
too large to be held entirely resident 
and had to be paged into memory in 
pieces; this paging resulted in many 
superfluous disk head movements 
as a program was reading through a 
file and degraded system through¬ 
put. In addition, because the infor¬ 
mation about free disk space was 
dispersed across many sectors of 
FAT, it was impractical to allocate 
file space contiguously, and file 
fragmentation became another obsta¬ 
cle to good performance. More¬ 
over, the use of relatively large 
clusters on fixed disks resulted in a 
lot of dead space, since an average 
of one-half cluster was wasted for 
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each file. (Some network servers 
use clusters as large as 64 KB.) 

The FAT file system’s restrictions 
on naming files and directories are 
inherited from CP/M. When Pater¬ 
son was writing 86-DOS, one of his 
primary objectives was to make pro¬ 
grams easy to port from CP/M to 
his new operating system. He there¬ 
fore adopted CP/M’s limits on 
filenames and extensions so the criti¬ 
cal fields of 86-DOS File Control 
Blocks (FCBs) would look almost 
exactly like those of CP/M. The 
sizes of the FCB filename and exten¬ 
sion fields were also propagated 
into the structure of disk directory 
entries. In due time, 86-DOS be¬ 
came MS-DOS and application pro¬ 
grams for MS-DOS proliferated 
beyond anyone’s wildest dreams. 
Since most of the early programs de¬ 
pended on the structure of FCBs, 
the 8.3 format for filenames became 
irrevocably locked into the system. 

During the last couple of years, 
Microsoft and IBM have made val¬ 
iant attempts to prolong the useful 
life of the FAT file system by lift¬ 
ing the restrictions on volume sizes, 
improving allocation strategies, 
caching pathnames, and moving ta¬ 
bles and buffers into expanded mem¬ 
ory. But these can only be regarded 
as temporizing measures, because 
the fundamental data structures used 
by the FAT file system are simply 
not well suited to large random ac¬ 
cess devices. 

The HPFS solves the FAT file sys¬ 
tem problems mentioned here and 
many others, but it is not derived in 
any way from the FAT file system. 
The architect of the HPFS started 
with a clean sheet of paper and de¬ 
signed a file system that can take 
full advantage of a multitasking en¬ 
vironment, and that will be able to 
cope with any sort of disk device 



FAT File System 

High Performance 

File System 

Maximum filename 
length 

11 (in 8.3 format) 

254 

Number of dot (.) 
delimeters allowed 

One 

Multiple 

File attributes 

Bit flags 

Bit flags plus up to 64 

KB of free-form ASCII 
or binary information 

Maximum path length 

64 

260 

Minimum disk space 
overhead per file 

Directory entry 
(32 bytes) 

Directory entry (length 
varies) + Fnode 
(512 bytes) 

Average wasted space 
per file 

1/2 cluster (typically 

2 KB or more) 

1/2 sector (256 bytes) 

Minimum allocation unit 

Cluster (typically 

4 KB or more) 

Sector (512 bytes) 

Allocation info for files 

Centralized in FAT on 
home track 

Located nearby each file 
in its Fnode 

Free disk space info 

Centralized in FAT on 
home track 

Located near free space 
in bitmaps 

Free disk space 
described per byte 

2 KB (1/2 cluster at 

8 sectors/cluster) 

4 KB (8 sectors) 

Directory structure 

Unsorted linear list, 
must be searched 
exhaustively 

Sorted B-Tree 

Directory location 

Root directory on home 
track, others scattered 

Localized near seek 
center of volume 

Cache replacement 
strategy 

Simple LRU 

Modified LRU, sensitive 
to data type and usage 
history 

Read-ahead 

None in MS-DOS 3.3 or 
earlier, primitive read- 
ahead optional in 

MS-DOS 4 

Always present, sensi¬ 
tive to data type and 
usage history 

Write-behind 

Not available 

Used by default, but can 
be defeated on 
per-handle basis 
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likely to arrive on microcomputers 
during the next decade. 

HPFS Volume Structure 

HPFS volumes are a new partition 
type - type 7 - and can exist on a 
fixed disk alongside of the several 
previously defined FAT partition 
types. IBM-compatible HPFS vol¬ 
umes use a sector size of 512 bytes 
and have a maximum size of 2199 
GB (2 32 sectors). Although there is 
no particular reason why floppy 
disks can’t be formatted as HPFS 
volumes, Microsoft plans to stick 
with FAT file systems on floppy 
disks for the foreseeable future. 

(This ensures that users will be able 
to transport files easily between MS- 
DOS and OS/2 systems.) 

An HPFS volume has very few 
fixed structures (Figure 1). Sectors 


0-15 of a volume (8 KB) are the 
BootBlock and contain a volume 
name, 32-bit volume ID, and a disk 
bootstrap program. The bootstrap is 
relatively sophisticated (by MS- 
DOS standards) and can use the 
HPFS in a restricted mode to locate 
and read the operating system files 
wherever they might be found. 

Sectors 16 and 17 are known as the 
SuperBlock and the SpareBlock re¬ 
spectively. The SuperBlock is only 
modified by disk maintenance utili¬ 
ties. It contains pointers to the free 
space bitmaps, the bad block list, 
the directory block band, and the 
root directory. It also contains the 
date that the volume was last 
checked out and repaired with 
CHKDSK/F. The SpareBlock con¬ 
tains various flags and pointers that 
will be discussed later; it is modi¬ 


fied, although infrequently, as the 
system executes. 

The remainder of the disk is divided 
into 8 MB bands. Each band has its 
own free space bitmap in which a 
bit represents each sector. A bit is 
0 if the sector is in use and 1 if the 
sector is available. The bitmaps are 
located at the head or tail of a band 
so that two bitmaps are adjacent be¬ 
tween alternate bands. This allows 
the maximum contiguous free space 
that can be allocated to a file to be 
16 MB. One band, located at or to¬ 
ward the seek center of the disk, is 
called the directory block band and 
receives special treatment (more 
about this later). Note that the band 
size is a characteristic of the current 
implementation and may be 
changed in later versions of the file 
system. 


Bitmap for Bitmap for Bitmap for Bitmap for Bitmap for Bitmap for 

Band 1 Band 2 Band 3 Band 4 Band n -1 Band n 



Volume Name 


Pointer to Bitmap Block 

List 


Hotfix Map 

Binary Volume ID 




Pointer to Hotfix Free 


Pointer to Bad Block List 


Block List 

BIOS Parameter Block 


Pointer to Directory Block 


Pointer to Directory 

Disk Bootstrap 


Band 


Emergency Free Block List 



Pointer to Fnode for Root 


File System Flags 



Directory 

Date of last CHKDSK/F 


Including DirtyFS 


Figure 1. This Figure shows the overall structure of an HPFS volume. The most important fixed objects in such a volume are the Boot- 
Block, the SuperBlock, and the SpareBlock. The remainder of the volume is divided into 8 MB bands. There is a freespace bitmap for 
each band and the bitmaps are located between alternate bands; consequently, the maximum contiguous space which can be allocated to a 
file is 16 MB. 
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Files and Fnodes 

Every file or directory on an HPFS 
volume is anchored on a fundamen¬ 
tal file system object called an 
Fnode (pronounced “eff node”). 

Each Fnode occupies a single sector 
and contains control and access his¬ 
tory information used internally by 
the file system, extended attributes 
and access control lists (more about 
this later), the length and the first 
15 characters of the name of the as¬ 
sociated file or directory, and an al¬ 
location structure (Figure 2). An 
Fnode is always stored near the file 
or directory that it represents. 

The allocation structure in the 
Fnode can take several forms, de¬ 
pending on the size and degree of 
contiguity of the file or directory. 
The HPFS views a file as a collec¬ 
tion of one or more runs or extents 
of one or more contiguous sectors. 
Each run is symbolized by a pair of 
doublewords - a 32-bit starting sec¬ 
tor number and a 32-bit length in 
sectors (this is referred to as run- 
length encoding). From an applica¬ 
tion program’s point of view, the 
extents are invisible; the file ap¬ 
pears as a seamless stream of bytes. 

The space reserved for allocation in¬ 
formation in an Fnode can hold 
pointers to as many as eight runs of 
sectors of up to 16 MB each. (This 
maximum run size is a result of the 
band size and free space bitmap 
placement only; it is not an inherent 
limitation of the file system.) Rea¬ 
sonably small files or highly contig¬ 
uous files can therefore be 
described completely within the 
Fnode (Figure 3). 

HPFS uses a new method to repre¬ 
sent the location of files that are too 
large or too fragmented for the 
Fnode and consist of more than 
eight runs. The Fnode’s allocation 


structure becomes the root for a B+ 
Tree of allocation sectors, which in 
turn contain the actual pointers to 
the file’s sector runs (see Figure 4 
and the section, “B-Trees and B+ 
Trees”). The Fnode’s root has 
room for 12 elements. Each alloca¬ 
tion sector can contain, in addition 


to various control information, as 
many as 40 pointers to sector runs. 
Therefore, a two-level allocation B+ 
Tree can describe a file of 480 
(12*40) sector runs, with a theoreti¬ 
cal maximum size of 7.68 GB 
(12*40*16 MB) in the current im¬ 
plementation (although the 32-bit 


Control Information 


Cached EAs and ACLs and/or 
Pointers to Storage for EAs and 
ACLs 


Truncated Name 


Allocation Structure 


Figure 2. This Figure shows the overall structure of an Fnode. The Fnode is the fundainen 
tal object in an HPFS volume and is the First sector allocated to a file or directory. It con¬ 
tains control and access history information used by the file system, cached EAs and ACLs 
or pointers to same, a truncated copy of the File or directory name (to aid disk repair pro¬ 
grams), and an allocation structure which defines the size and location of the file's storage. 
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Figure 3. The simplest form of tracking for the sectors owned by a file is shown. The 
Fnode’s allocation structure points directly to as many as eight sector runs. Each run 
pointer consists of a pair of 32-bit doublewords: a starting sector number, and a length 
in sectors. 
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signed offset parameter for 
DosChgFilePtr effectively limits file 
sizes to 2 GB). 

In the unlikely event that a two- 
level B+ Tree is not sufficient to de¬ 
scribe a highly fragmented file, the 
file system will introduce additional 
levels in the tree as needed. Alloca¬ 
tion sectors in the intermediate lev¬ 
els can hold as many as 60 internal 
(nonterminal) B+ Tree nodes, which 
means that the descriptive ability of 
this structure rapidly grows to num¬ 
bers that are nearly beyond compre¬ 
hension. For example, a three-level 
allocation B+ Tree can describe a 
file with as many as 28,800 
(12*60*40) sector runs. 

Run-length encoding and B+ Trees 
of allocation sectors are a memory- 
efficient way to specify a file’s size 
and location, but they have other 
significant advantages. Translating 
a logical file offset into a sector 
number is extremely fast: the file 
system just needs to traverse the list 
(or B+ Tree of lists) of run pointers 
until it finds the correct range. It 


can then identify the sector within 
the run with a simple calculation. 
Run-length encoding also makes it 
trivial to extend the file logically if 
the newly assigned sector is contigu¬ 
ous with the file’s previous last sec¬ 
tor; the file system merely needs to 
increment the size doubleword of 
the file’s last run pointer and clear 
the sector’s bit in the appropriate 
freespace bitmap. 

Directories 

Directories, like files, are anchored 
on Fnodes. A pointer to the Fnode 
for the root directory is found in the 
SuperBlock. The Fnodes for direc¬ 
tories other than the root are 
reached through subdirectory entries 
in their parent directories. 

Directories can grow to any size 
and are built up from 2 KB direc¬ 
tory blocks, which are allocated as 
four consecutive sectors on the disk. 
The file system attempts to allocate 
directory blocks in the directory 
band, which is located at or near the 
seek center of the disk. Once the di¬ 
rectory band is full, the directory 


blocks are allocated wherever space 
is available. 

Each 2 KB directory block contains 
from one to many directory entries. 
A directory entry contains several 
fields, including time and date 
stamps, an Fnode pointer, a usage 
count for use by disk maintenance 
programs, the length of the file or 
directory name, the name itself, and 
a B-Tree pointer. Each entry begins 
with a word that contains the length 
of the entry. This provides for a 
variable amount of flex space at the 
end of each entry, which can be 
used by special versions of the file 
system and allows the directory 
block to be traversed very quickly 
(Figure 5). 

The number of entries in a directory 
block varies with the length of 
names. If the average filename 
length is 13 characters, an average 
directory block will hold about 40 
entries. The entries in a directory 
block are sorted by the binary lexi¬ 
cal order of their name fields (this 
happens to put them in alphabetical 



Figure 4. This figure demonstrates the technique used to track the sectors owned by a file with 9^180 sector runs. The allocation structure 
in the Fnode holds the roots for a B+ Tree of allocation sectors. Each allocation sector can describe as many as 40 sector runs. If the file re¬ 
quires more than 480 sector runs, additional intermediate levels are added to the B+ Tree, which increases the number of possible sector 
runs by a factor of sixty for each new level. 
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order for the U.S. alphabet). The 
last entry in a directory block is a 
dummy record that marks the end 
of the block. 

When a directory gets too large to 
be stored in one block, it increases 
in size by the addition of 2 KB 
blocks that are organized as a B- 
Tree (see “B-Trees and B+ Trees”). 
When searching for a specific 


name, the file system traverses a di¬ 
rectory block until it either finds a 
match or finds a name that is lexi¬ 
cally greater than the target. In the 
latter case, the file system extracts 
the B-Tree pointer from the entry. 

If there is no pointer, the search 
failed; otherwise the file system fol¬ 
lows the pointer to the next direc¬ 
tory block in the tree and continues 
the search. 


A little back-of-the-envelope arith¬ 
metic yields some impressive statis¬ 
tics. Assuming 40 entries per 
block, a two-level tree of directory 
blocks can hold 1,640 directory en¬ 
tries and a three-level tree can hold 
an astonishing 65,640 entries. In 
other words, a particular file can be 
found (or shown not to exist) in a 
typical directory of 65,640 files 
with a maximum of three disk hits 



Directory Leaf 
blocks 


\ 


\ 

\ 


\ 


\ 


Length of Entry 
N Flags 
Fnode Pointer 
Time and Date Created 
Time and Date Last Access 
Time and Date Last Modified 
Length of EAs 
Usage Count 
Length of Name 
Name (1-254 characters) 
B-Tree Pointer 
Flex Space 


Contents of a 
Directory Entry 


The symbol * indicates a special record that indicates the end of the directory block 


Figure 5. Here, directories are anchored on an Fnode and are built up from 2 KB directory blocks. The number of entries in a directory 
block varies because the length of the entries depends on the filename. When a directory requires more than one block, the blocks are or¬ 
ganized as a B-Tree. This allows a filename to be located very quickly with a small number of disk accesses, even when the directory grows 
very large. 
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the actual number of disk accesses 
depending on cache contents and 
the location of the file’s name in the 
directory block B-Tree. That’s 
quite a contrast to the FAT file sys¬ 
tem, where in the worst case more 
than 4,000 sectors would have to be 
read to establish that a file was or 
was not present in a directory con¬ 
taining the same number of files. 

The B-Tree directory structure has 
interesting implications beyond its 
effect on open and find operations. 

A file creation, renaming, or dele¬ 
tion may result in a cascade of com¬ 
plex operations, as directory blocks 
are added or freed or names are 
moved from one block to the other 
to keep the tree balanced. In fact, a 
rename operation could theoreti¬ 
cally fail for lack of disk space even 
though the file itself is not growing. 
In order to avoid this sort of disas¬ 
ter, the HPFS maintains a small 
pool of free blocks that can be 
drawn from in a directory emer¬ 
gency; a pointer to this pool of free 
blocks is stored in the SpareBlock. 

Extended Attributes 

File attributes are information about 
a file that is maintained by the oper¬ 
ating system outside the file’s overt 
storage area. The FAT file system 
supports only a few simple attri¬ 
butes (read only, system, hidden, 
and archive) that are actually stored 
as bit flags in the file’s directory 
entry; these attributes are inspected 
or modified by special function 
calls and are not accessible through 
the normal file open, read, and 
write calls. 

The HPFS supports the same attri¬ 
butes as the FAT file system for his¬ 
torical reasons, but it also supports 
a new form of file-associated, 
highly generalized information 
called Extended Attributes (EAs). 


Each EA is conceptually similar to 
an environment variable, taking the 
form 

name=value 

except that the value portion can be 
either a null-terminated (ASCIIZ) 
string or binary data. In OS/2 1.2, 
each file or directory can have a 
maximum of 64 KB of EAs at¬ 
tached to it. This limit may be 
lifted in a later release of OS/2. 

The storage method for EAs can 
vary. If the EAs associated with a 
given file or directory are small 
enough, they will be stored right in 
the Fnode. If the total size of the 
EAs is too large, they are stored out¬ 
side the Fnode in sector runs, and a 
B+ Tree of allocation sectors can be 
created to describe the runs. If a 
single EA gets too large, it can be 
pushed outside the Fnode into a B+ 
Tree of its own. 

The kernel API functions 
DosQFilelnfo and DosSetFilelnfo 
have been expanded with new infor¬ 
mation levels that allow application 
programs to manipulate extended at¬ 
tributes for files. The new func¬ 
tions DosQPathlnfo and 
DosSetPathlnfo are used to read or 
write the EAs associated with arbi¬ 
trary pathnames. An application 
program can either ask for the value 
of a specific EA (supplying a name 
to be matched) or can obtain all of 
the EAs for the file or directory at 
once. 

Although application programs can 
begin to take advantage of EAs as 
soon as the HPFS is released, sup¬ 
port for EAs is an essential compo¬ 
nent in Microsoft’s long-range plans 
for object-oriented file systems. In¬ 
formation of almost any type can be 
stored in EAs, ranging from the 
name of the application that owns 


the file to names of dependent files 
to icons to executable code. As the 
HPFS evolves, its facilities for ma¬ 
nipulating EAs are likely to become 
much more sophisticated. It’s easy 
to imagine, for example, that in fu¬ 
ture versions the API might be ex¬ 
tended with EA functions that are 
analogous to DosFindFirst and 
DosFindNext and EA data might 
get organized into B-Trees. 

I should note here that in addition 
to EAs, the LAN Manager version 
of HPFS will support another class 
of file-associated information called 
Access Control Lists (ACLs). 

ACLs have the same general appear¬ 
ance as EAs and are manipulated in 
a similar manner, but they are used 
to store access rights, passwords, 
and other information of interest in 
a networking multiuser environment. 

Installable File Systems 

Support for installable file systems 
has been one of the most eagerly an¬ 
ticipated features of OS/2 Version 
1.2. It will make it possible to ac¬ 
cess multiple incompatible volume 
structures - FAT, HPFS, CD ROM, 
and perhaps even UNIX® on the 
same OS/2 system at the same time, 
will simplify the life of network im¬ 
plementors, and will open the door 
to rapid file system evolution and in¬ 
novation. Installable file systems 
are, however, only relevant to the 
HPFS insofar as they make use of 
the HPFS optional. The FAT file 
system is still embedded in the 
OS/2 kernel, as it was in OS/2 1.0 
and 1.1, and will remain there as 
the compatibility file system for 
some time to come. 

An installable file system driver 
(FSD) is analogous in many ways to 
a device driver. An FSD resides on 
the disk in a file that is structured 
like a dynamic-link library (DLL), 
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typically with a SYS or IFS exten¬ 
sion, and is loaded during system 
initialization by IFS= statements in 
the CONFIG.SYS file. IFS= direc¬ 
tives are processed in the order they 
are encountered and are also sensi¬ 
tive to the order of DEVICE= state¬ 
ments for device drivers. This lets 
you load a device driver for a non¬ 
standard device, load a file system 
driver from a volume on that de¬ 
vice, and so on. 

Once an FSD is installed and initial¬ 
ized, the kernel communicates with 
it in terms of logical requests for 
file opens, reads, writes, seeks, 
closes, and so on. The FSD trans¬ 
lates these requests - using control 
structures and tables found on the 
volume itself - into requests for sec¬ 
tor reads and writes for which it can 
call special kernel entry points 
called File System Helpers 
(FsHlps). The kernel passes the de¬ 
mands for sector I/O to the appropri¬ 
ate device driver and returns the 
results to the FSD (Figure 6). 

The procedure used by the operat¬ 
ing system to associate volumes 
with FSDs is called dynamic mount¬ 
ing and works as follows. When¬ 
ever a volume is first accessed, or 
after it has been locked for direct ac¬ 
cess and then unlocked (for exam¬ 
ple, by a FORMAT operation), 

OS/2 presents identifying informa¬ 
tion from the volume to each of the 
FSDs in turn until one of them rec¬ 
ognizes the information. When an 
FSD claims the volume, the volume 
is mounted and all subsequent file 
I/O requests for the volume are 
routed to that FSD. 

Performance Issues 

The HPFS attacks potential bottle¬ 
necks in disk throughput at multiple 
levels. It uses advanced data struc¬ 
tures, contiguous sector allocation, 


intelligent caching, read-ahead, and 
deferred writes in order to boost per¬ 
formance. 

First, the HPFS matches its data 
structures to the task at hand: sophis¬ 
ticated data structures (B-Trees and 
B+ Trees) for fast random access to 


filenames, directory names, and lists 
of sectors allocated to files or direc¬ 
tories, and simple compact data 
structures (bitmaps) for locating 
chunks of free space of the appropri¬ 
ate size. The routines that manipu¬ 
late these data structures are written 
in assembly language and have been 



Figure 6. This is a simplified sketch of the relationship between an application program, 
the OS/2 kernel, an installable file system, a disk driver, and the physical disk device. The 
application issues logical file requests to the OS/2 kernel by calling the entry points for 
DosOpen, DosRead, DosWrite, DosChgFilePtr, and so on. The kernel passes these requests 
to the appropriate installable file system for the volume holding the file. The installable file 
system sectors translates the logical file requests into requests for reads or writes of logical 
sectors and calls a kernel File System Helper (FsHIp) to pass these requests to the appropri¬ 
ate disk driver. The disk driver transforms the logical sector requests into requests for spe¬ 
cific physical units, cylinders, heads, and sectors, and issues commands to the disk adapter 
to transfer data between the disk and memory. 
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painstakingly tuned, with special 
focus on the routines that search the 
freespace bitmaps for patterns of set 
bits (unused sectors). 

Next, the HPFS’s main goal - its 
prime directive, if you will - is to 
assign consecutive sectors to files 
whenever possible. The time re¬ 
quired to move the disk’s read/write 
head from one track to another far 
outweighs the other possible delays, 
so the HPFS works hard to avoid or 
minimize such head movements by 
allocating file space contiguously 
and by keeping control structures 
such as Fnodes and freespace 
bitmaps near the things they con¬ 
trol. Highly contiguous files also 
help the file system make fewer re¬ 
quests of the disk driver for more 
sectors at a time, allow the disk 
driver to exploit the multisector 
transfer capabilities of the disk con¬ 
troller, and reduce the number of 
disk completion interrupts that must 
be serviced. 

Of course, trying to keep files from 
becoming fragmented in a multitask¬ 
ing system in which many files are 
being updated concurrently is no 
easy chore. One strategy the HPFS 
uses is to scatter newly created files 
across the disk - in separate bands, 
if possible - so that the sectors allo¬ 
cated to the files as they are ex¬ 
tended will not be interleaved. 
Another strategy is to preallocate ap¬ 
proximately 4 KB of contiguous 
space to the file each time it must 
be extended and give back any ex¬ 
cess when the file is closed. 

If an application knows the ultimate 
size of a new file in advance, it can 
assist the file system by specifying 
an initial file allocation when it cre¬ 
ates the file. The system will then 
search all the free space bitmaps to 
find a run of consecutive sectors 
large enough to hold the file. That 


failing, it will search for two runs 
that are half the size of the file, and 
so on. 

The HPFS relies on several differ¬ 
ent kinds of caching to minimize 
the number of physical disk trans¬ 
fers it must request. Naturally, it 
caches sectors, as did the FAT file 
system. But unlike the FAT file sys¬ 
tem, the HPFS can manage very 
large caches efficiently and adjusts 
sector caching on a per-handle basis 
to the manner in which a file is 
used. The HPFS also caches 
pathnames and directories, trans¬ 
forming disk directory entries into 
an even more compact and efficient 
in-memory representation. 

Another technique that the HPFS 
uses to improve performance is to 
preread data it believes the program 
is likely to need. For example, 
when a file is opened, the file sys¬ 
tem will preread and cache the 
Fnode and the first few sectors of 
the file’s contents. If the file is an 
executable program or the history in¬ 
formation in the file’s Fnode shows 
that an open operation has typically 
been followed by an immediate se¬ 
quential read of the entire file, the 
file system will preread and cache 
much more of the file’s contents. 
When a program issues relatively 
small read requests, the file system 
always fetches data from the file in 
2 KB chunks and caches the excess, 
allowing most read operations to be 
satisfied from the cache. 

Finally, the OS/2 operating system’s 
support for multitasking makes it 
possible for the HPFS to rely heav¬ 
ily on lazy writes (sometimes called 
deferred writes or write behind) to 
improve performance. When a pro¬ 
gram requests a disk write, the data 
is placed in the cache and the cache 
buffer is flagged as dirty (that is, in¬ 
consistent with the state of the data 


on disk). When the disk becomes 
idle or the cache becomes saturated 
with dirty buffers, the file system 
uses a captive thread from a dae¬ 
mon process to write the buffers to 
disk, starting with the oldest data. 

In general, lazy writes mean that 
programs run faster because their 
read requests will almost never be 
stalled waiting for a write request to 
complete. For programs that repeat¬ 
edly read, modify, and write a small 
working set of records, it also 
means that many unnecessary or re¬ 
dundant physical disk writes may be 
avoided. Lazy writes have their 
dangers, of course, so a program 
can defeat them on a per-handle 
basis by setting the write-through 
flag in the OpenMode parameter for 
DosOpen, or it can commit data to 
disk on a per-handle basis with the 
DosBufReset function. 

Fault Tolerance 

The HPFS’s extensive use of lazy 
writes makes it imperative for the 
HPFS to be able to recover grace¬ 
fully from write errors under any 
but the most dire circumstances. 
After all, by the time a write is 
known to have failed, the applica¬ 
tion has long since gone on its way 
under the illusion that it has safely 
shipped the data into disk storage. 
The errors may be detected by the 
hardware (such as a “sector not 
found’’ error returned by the disk 
adapter), or they may be detected 
by the disk driver in spite of the 
hardware during a read-after-write 
verification of the data. 

The primary mechanism for han¬ 
dling write errors is called a hotfix. 
When an error is detected, the file 
system takes a free block out of a re¬ 
served hotfix pool, writes the data 
to that block, and updates the hotfix 
map. (The hotfix map is simply a 
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series of pairs of doublewords, with 
each pair containing the number of 
a bad sector associated with the 
number of its hotfix replacement. 

A pointer to the hotfix map is main¬ 
tained in the SpareBlock.) A copy 
of the hotfix map is then written to 
disk, and a warning message is dis¬ 
played to let the user know that all 
is not well with the disk device. 

Each time the file system requests a 
sector read or write from the disk 
driver, it scans the hotfix map and 
replaces any bad sector numbers 
with the corresponding good sector 
holding the actual data. This look 
aside translation of sector numbers 
is not as expensive as it sounds, 
since the hotfix list need only be 
scanned when a sector is physically 
read or written, not each time it is 
accessed in the cache. 

One of CHKDSK’s duties is to 
empty the hotfix map. For each re¬ 
placement block on the hotfix map, 
it allocates a new sector that is in a 
favorable location for the file that 
owns the data, moves the data from 
the hotfix block to the newly allo¬ 
cated sector, and updates the file’s 
allocation information (which may 
involve rebalancing allocation trees 
and other elaborate operations). It 
then adds the bad sector to the bad 
block list, releases the replacement 
sector back to the hotfix pool, de¬ 
letes the hotfix entry from the hotfix 
map, and writes the updated hotfix 
map to disk. 

Of course, write errors that can be 
detected and fixed on the fly are not 
the only calamity that can befall a 
file system. The HPFS designers 
also had to consider the inevitable 
damage to be wreaked by power 
failures, program crashes, malicious 
viruses and Trojan horses, and those 
users who turn off the machine with¬ 
out selecting Shutdown in the Pre¬ 


sentation Manager Shell. (Shut¬ 
down notifies the file system to 
flush the disk cache, update directo¬ 
ries, and do whatever else is neces¬ 
sary to bring the disk to a consistent 
state.) 

The HPFS defends itself against the 
user who is too abrupt with the Big 
Red Switch by maintaining a Dirty 
FS flag in the SpareBlock of each 
HPFS volume. The flag is only 
cleared when all files on the volume 
have been closed and all dirty buff¬ 
ers in the cache have been written 
out or, in the case of the boot vol¬ 
ume (since OS2.IN1 and the swap 
file are never closed), when Shut¬ 
down has been selected and has 
completed its work. 

During the OS/2 boot sequence, the 
file system inspects the DirtyFS flag 
on each HPFS volume and, if the 
flag is set, will not allow further ac¬ 
cess to that volume until CHKDSK 
has been run. If the DirtyFS flag is 
set on the boot volume, the system 
will refuse to boot; the user must 
boot OS/2 in maintenance mode 
from a diskette and run CHKDSK 
to check and possibly repair the 
boot volume. 

In the event of a truly major catas¬ 
trophe, such as loss of the 
SuperBlock or the root directory, 
the HPFS is designed to give data 
recovery the best possible chance of 
success. Every type of crucial file 
object - including Fnodes, alloca¬ 
tion sectors, and directory blocks - 
is doubly linked to both its parent 
and its children and contains a 
unique 32-bit signature. Fnodes 
also contain the initial portion of 
the name of their file or directory. 
Consequently, CHKDSK can re¬ 
build an entire volume by methodi¬ 
cally scanning the disk for Fnodes, 
allocation sectors, and directory 
blocks, using them to reconstruct 


the files and directories and finally 
regenerating the freespace bitmaps. 

Application Programs and 
the HPFS 

Each of the OS/2 releases thus far 
have carried with them a major dis¬ 
continuity for application program¬ 
mers who learned their trade in the 
MS-DOS environment. In OS/2 
1.0, such programmers were faced 
for the first time with virtual mem¬ 
ory, multitasking, interprocess com¬ 
munications, and the protected 
mode restrictions on addressing and 
direct control of the hardware and 
were challenged to master powerful 
new concepts such as threading and 
dynamic linking. In OS/2 Version 
1.1, the stakes were raised even fur¬ 
ther. Programmers were offered a 
powerful hardware-independent 
graphical user interface but had to 
restructure their applications drasti¬ 
cally for an event-driven environ¬ 
ment based on objects and message 
passing. 

In OS/2 Version 1.2, it is time for 
many of the file-oriented program¬ 
ming habits and assumptions carried 
forward from the MS-DOS environ¬ 
ment to fall by the wayside. An ap¬ 
plication that wishes to take full 
advantage of the HPFS must allow 
for long, free-form, mixed-case 
filenames and paths with few restric¬ 
tions on punctuation and must be 
sensitive to the presence of EAs and 
ACLs. After all, if EAs are to be of 
any use, it won’t suffice for applica¬ 
tions to update a file by renaming 
the old file and creating a new one 
without also copying the EAs. 

But the necessary changes for OS/2 
Version 1.2 are not tricky to make. 

A new API function, DosCopy, 
helps applications create backups - 
it essentially duplicates an existing 
file together with its EAs. EAs can 
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also be manipulated explicitly with 
DosQFilelnfo, DosSetFilelnfo, 
DosQPathlnfo, and DosSetPathlnfo. 
A program should call 
DosQSysInfo at run time to find the 
maximum possible path length for 
the system, and ensure that all buff¬ 
ers used by DosChDir, 

DosQCurDir, and related functions 
are sufficiently large. Similarly, the 
buffers used by DosOpen, 

DosMove, DosGetModName, 
DosFindFirst, DosFindNext, and 
like functions must allow for longer 
filenames. Any logic that folds 
cases in filenames or tests for the oc¬ 
currence of only one dot delimiter 
in a filename must be rethought or 
eliminated. 

The other changes in the API will 
not affect the average application. 
The functions DosQFilelnfo, 
DosFindFirst, and DosFindNext 
now return all three sets of times 
and dates (created, last accessed, 
last modified) for a file on an HPFS 
volume, but few programs are con¬ 
cerned with time and date stamps 
anyway. DosQFsInfo is used to ob¬ 
tain volume labels or disk character¬ 
istics just as before, and the use of 
DosSetFsInfo for volume labels is 
unchanged. There are a few totally 
new API functions such as 
DosFsCtl (analogous to 
DosDevIOCtl but used for commu¬ 
nication between an application and 
an FSD), DosFsAttach (a sort of ex¬ 
plicit mount call), and 
DosQFsAttach (determines which 
FSD owns a volume); these are in¬ 
tended mainly for use by disk utility 
programs. 

In order to prevent old OS/2 applica¬ 
tions and MS-DOS applications run¬ 
ning in the DOS box from 
inadvertently damaging HPFS files, 
a new flag bit has been defined in 
the EXE file header that indicates 
whether an application is HPFS- 


aware. If this bit is not set, the ap¬ 
plication will only be able to search 
for, open, or create files on HPFS 
volumes that are compatible with 
the FAT file system’s 8.3 naming 
conventions. If the bit is set, OS/2 
allows access to all files on an 
HPFS volume, because it assumes 
that the program knows how to han¬ 
dle long, free-form filenames and 
will take the responsibility of con¬ 
serving a file’s EAs and ACLs. 

Summary 

The HPFS solves all of the histori¬ 
cal problems of the FAT file sys¬ 
tem. It achieves excellent 
throughput even in extreme cases - 
many very small files or a few very 
large files- by means of advanced 
data structures and techniques such 
as intelligent caching, read-ahead, 
and write-behind. Disk space is 
used economically because it is 
managed on a sector basis. Existing 
application programs will need mod¬ 
ification to take advantage of the 
HPFS’s support for extended attri¬ 
butes and long filenames, but these 
changes will not be difficult. All ap¬ 
plication programs will benefit from 
the HPFS’s improved performance 
and decreased CPU use whether 
they are modified or not. This arti¬ 
cle is based on a prerelease version 
of the HPFS that was still undergo¬ 
ing modification and tuning. There¬ 
fore, the final release of the HPFS 
may differ in some details from the 
description given here. 

B-Trees and B+ Trees 

Most programmers are at least 
passingly familiar with the data 
structure known as a binary tree. 
Binary trees are a technique for im¬ 
posing a logical ordering on a col¬ 
lection of data items by means of 
pointers, without regard to the physi¬ 
cal order of the data. 


In a simple binary tree, each node 
contains some data, including a key 
value that determines the node’s log¬ 
ical position in the tree, as well as 
pointers to the node’s left and right 
subtrees. The node that begins the 
tree is known as the root; the nodes 
that sit at the ends of the tree’s 
branches are sometimes called the 
leaves. 

To find a particular piece of data, 
the binary tree is traversed from the 
root. At each node, the desired key 
is compared with the node’s key; if 
they don’t match, one branch of the 
node’s subtree or another is selected 
based on whether the desired key is 
less than or greater than the node’s 
key. This process continues until a 
match is found or an empty subtree 
is encountered (Figure 7a). 

Such simple binary trees, although 
easy to understand and implement, 
have disadvantages in practice. If 
keys are not well distributed or are 
added to the tree in a non-random 
fashion, the tree can become quite 
asymmetric, leading to wide varia¬ 
tions in tree traversal times. 

In order to make access times uni¬ 
form, many programmers prefer a 
particular type of balanced tree 
known as a B-Tree. For the pur¬ 
poses of this discussion, the impor¬ 
tant points about a B-Tree are that 
data is stored in all nodes, more 
than one data item might be stored 
in a node, and all of the branches of 
the tree are of identical length 
(Figure 7b). 

The worst-case behavior of a B- 
Tree is predictable and much better 
than that of a simple binary tree, but 
the maintenance of a B-Tree is cor¬ 
respondingly more complex. Add¬ 
ing a new data item, changing a key 
value, or deleting a data item may 
result in the splitting or merging of 
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a node, which in turn forces a cas¬ 
cade of other operations on the tree 
to rebalance it. 

A B+ Tree is a specialized form of 
B-Tree that has two types of nodes: 
internal, which only point to other 
nodes, and external, which contain 
the actual data (Figure 7c). 

The advantage of a B+ Tree over a 
B-Tree is that the internal nodes of 
the B+ Tree can hold many more de 
cision values than the intermediate- 
level nodes of a B-Tree, so the fan 
out of the tree is faster and the aver¬ 
age length of a branch is shorter. 

This makes up for the fact that you 
must always follow a B+ Tree 
branch to its end to get the data for 
which you are looking, whereas in a 
B-Tree you may discover the data 
at an intermediate node or even at 
the root. 

Note 1 : As used herein, “OS/2" re¬ 
fers to the OS/2 operating system 
jointly developed by Microsoft and 
IBM. 

Note 2: “MS-DOS” refers to the 
Microsoft MS-DOS Operating sys- Figure 7b. In a balanced B-Tree, data is stored in nodes, more than one data item can be 

tern and not to such products gener- stored in a node, and all branches of the tree are the same length, 

ally. 



Figure 7a. To find a piece of data, the binary tree is traversed from the root until the data 
is found or an empty subtree is encountered. 
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OS/2 EE 1.2 
Database 
Manager - 
Remote Data 
Services 

Romelia Flores 
IBM Corporation 
Dallas , Texas 

This article discusses the 
Communications Manager APPC 
configuration process for Remote 
Data Services. In addition, it con¬ 
tains information for installing Re¬ 
mote Data Services. 


Database Manager consists of two 
major features: Database Services 
and Query Manager. Database Ser¬ 
vices is the engine or heart of the 
Database Manager. Database Ser¬ 
vices processes Structured Query 
Language (SQL) statements that are 
embedded within an application. It 
also contains a set of Application 
Programming Interfaces (APIs) that 
allow an application programmer to 
change the processing environment 
for Database Manager (configura¬ 
tion files, etc.), and gain access to 
utilities (import, export, etc.). 

Query Manager is the end-user inter¬ 
face provided with OS/2 Database 
Manager. Query Manager is itself 
an application program that inter¬ 


faces with Database Services in 
order to externalize the functions of 
Database Services. 

One of the major enhancements to 
the OS/2 Database Manager in Ex¬ 
tended Edition 1.2 is the addition of 
Remote Data Services (RDS) com¬ 
ponents - RDS Requester and RDS 
Server. These components are part 
of the Database Services engine. 
They make it possible for an appli¬ 
cation program residing on an OS/2 
workstation, or for the end user of 
such an application, to gain transpar¬ 
ent access to data residing in an 
OS/2 Database on a remote worksta¬ 
tion. 

RDS uses the Advanced Program-to- 
Program Communication (APPC) in¬ 
terface of OS/2 Communications 
Manager (CM), thus providing sup¬ 
port of several different communica¬ 
tions media by simply adjusting CM 
profiles. IBM Token-Ring, IBM 
PC Network, Ethernet (DIX V2.0 
and IEEE 802.3), X.25, and SDLC 
are supported. The use of APPC 
also paves the way for the imple¬ 
mentation of Distributed Database 
Services to the other Systems Appli¬ 
cation Architecture (SAA) platforms. 

Although the actual manner in 
which data is transported in the 
RDS environment is transparent to 
the end user, the installation and 
configuration for the RDS environ¬ 
ment requires knowledge of APPC 
configuration. The RDS Requester 
and RDS Server components do not 
use the Local Area Network (LAN) 
Requester component of OS/2 EE 
1.2 or the LAN Server 1.2 product. 
However, the LAN Requester or 
LAN Server can reside on the same 
LAN or workstation as the RDS Re¬ 
quester or RDS Server. 

RDS is designed for multiuser ac¬ 
cess to a database. Therefore multi- 
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pie RDS Requesters can simulta¬ 
neously access the same database 
on an RDS Server. A separate pro¬ 
cess is started on the RDS Server 
on behalf of each remote connection 
to a Server database. For example, 
if two programs on an RDS Re¬ 
quester connect to a database on the 
same RDS Server, two processes 
will be started. Database Manager 
enforces serialized execution of 
SQL statements at the thread level, 
not the process level; therefore, con¬ 
current access is possible. 

This article focuses on the Commu¬ 
nications Manager APPC configura¬ 
tion process for RDS and provides 
other information for installing 
RDS. Information on APPC, spe¬ 
cific APPC parameters, and how to 
configure Communications Manager 
for APPC is provided in the IBM 
Operating System!2 Extended Edi¬ 
tion Systems Administrator s Guide 
for Communications , SO 1F-0261. 

SQL LAN-Only Option 

The implementation of RDS pro¬ 
vides a special Transmission Ser¬ 
vice Mode named SQL LAN-Only 
Option (SQLLOO), which yields a 
performance enhancement for the 
LAN environments. SQLLOO does 
not apply to the SDLC or X.25 envi¬ 
ronments. 

The Subsystems Management and 
remote operator facilities provided 
by Communications Manager are 
not available when SQLLOO is 
used. This means that a user will 
not be able to view or deactivate 
any SQLLOO sessions or link sta¬ 
tions. Hence, the recommended ap¬ 
proach for initially setting up RDS 
is to use APPC by creating a Trans¬ 
mission Service Mode profile 
(named anything other than 
SQLLOO) and specifying this Trans¬ 
mission Service Mode profile name 


in the Partner Logical Unit (LU) 
profile. When successful access to 
a remote database is achieved, the 
user can modify the Transmission 
Service mode profile and the Part¬ 
ner LU profile to specify SQLLOO. 
(The remote workstation must also 
be uncataloged and recataloged with 
the SQLLOO.) 

Data Link Control (DLC) 

Considerations 

When using a transmission mode 
other than SQLLOO for communica¬ 
tion, the link stations defined in the 
DLC profile are used. When using 
SQLLOO for communication, the 
link stations defined in the DLC pro¬ 
file are not used. Instead, the 
SQLLOO uses link stations defined 
in the IEEE 802.2 profile. It uses 
80% of the remaining link stations 
after subtracting the DLC and 
NETBIOS link stations. When con¬ 
figuring your system, make sure 
that the parameter settings for link 
stations provide some extra link sta¬ 
tions that can be used by SQLLOO, 
because it is the last function loaded 
that requires link stations. For ex¬ 
ample, if the IEEE 802.2 profile has 
the link stations parameter set to 8, 
and your NETBIOS and DLC link 
stations are each set to 4, that does 


not leave any link stations available 
for SQLLOO. SQLLOO needs one 
link station available on the RDS 
Requester and one link station per 
RDS Requester available on the 
RDS Server. 

APPC Configuration 

Because RDS uses the APPC inter¬ 
faces of OS/2 Communications 
Manager, APPC profiles will need 
to be configured appropriately. The 
profiles that need to be configured 
depend on whether the workstation 
is an RDS Requester or RDS 
Server. By configuring additional 
partner profiles, a Server may also 
perform Requester functions. In 
this article this configuration will be 
referred to as RDS Re¬ 
quester/Server. The profiles needed 
in each situation are shown in Fig¬ 
ure 1. An “X” in the figure signi¬ 
fies that more than one of these 
profiles may be needed to gain ac¬ 
cess to multiple Servers, or to use 
different transmission service modes 
or initial session limits. 

Some of the complexity of configur¬ 
ing the RDS environment is re¬ 
lieved through the use of Basic 
Configuration Services (BCS). Dur¬ 
ing installation, BCS provides de- 


Profile 

RDS 

Requester 

RDS 

Server 

(Additional ) 
RDS Server/ 
Requester 

Workstation 

1 

1 


IEEE 802.2 

1 

1 


SNA Base 

1 

1 


DLC 

1 

1 


Local LU 

1 

1 


Partner LU 

X 

1 

X 

Transmiss. Service Mode 

X 

1 

X 

Initial Session Limits 

X 

0 

X 

Remotely Attached TPs 

0 

2 


Conversation Security 

0 

1 



Figure 1. CM Profiles for RDS 
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fault configuration files required to 
have one RDS Requester communi¬ 
cate with one RDS Server in the 
IBM Token-Ring environment. 

BCS determines which type of con¬ 
figuration file to create by prompt¬ 
ing the user to specify whether each 
workstation will be an RDS Re¬ 
quester, RDS Server, or both Re¬ 
quester and Server. The CM 
Advanced Configuration Services 
can be used to modify the BCS con¬ 
figuration files for different connec¬ 
tivity, to access multiple RDS 
Servers, and to specify other 
changes to the environment. 


Following is a description of the de¬ 
fault values provided in the configu¬ 
ration files when configuring RDS 
via BCS for the IBM Token-Ring 
Network. 

Workstation Profile: This profile 
contains information about the work¬ 
station, auto-start options, and mes¬ 
sage/error log sizes (Figure 2). 

If RDS is configured to take advan¬ 
tage of the SQLLOO, and applica¬ 
tions residing on this workstation do 
not require APPC, the Workstation 
Profile parameter to enable auto¬ 
start options can be modified to not 


load Sytems Network Architecture 
(SNA)/APPC. 

SNA Base Profile: This profile 
contains parameters pertaining to 
APPC (Figure 3). 

The Physical Unit (PU) Name and 
Network Name are used by RDS 
when recording information in the 
OS/2 Error Log and generating 
alerts. If configuring strictly for the 
LAN environment, the PU Name 
and Network name parameters can 
be left with the default values. Oth¬ 
erwise, the naming scheme put in 
place by the Network Administrator 
should be used. Auto-Activate At¬ 
tach Manager must be set to YES 
on the RDS Server workstation in 
order to accept requests initiated by 
RDS Requesters. 

DLC Profile: This profile contains 
information about adapters being 
used for APPC or 3270 terminal em¬ 
ulation (Figure 4). 

The DLC profile should be config¬ 
ured for the type of connectivity 
used for RDS. If SQLLOO is not 
used, the RDS Server should have 
one link station defined for every 
RDS Requester that accesses it. 

NETBIOS Profile: This profile 
contains parameters pertaining to 
the NETBIOS interface (Figure 5). 

The 802.2 link station value must 
be greater than or equal to the sum 
of the DLC link stations and the 
NETBIOS link stations. The maxi¬ 
mum number of link stations in this 
profile should be taken into account 
during configuration. 

IEEE 802.2 Profile: This profile 
contains specific information about 
the LAN logical link control 
(Figure 6). 


Workstation Profile 

BCS RDS Requester 

BCS RDS Server 

Services to load 

SNA/APPC 

SNA/APPC 

Autostart 

Yes 

Yes 


Figure 2. Workstation Profile 


SNA Base Profile 

BCS RDS Requester 

BCS RDS Server 

Autoact. Attach Manager 

No 

Yes 

PU Name 

PU000000 

PU000000 

Network Name 

BLANK 

BLANK 


Figure 3. SNA Base Profile 


DLC Profile /IBM TR 
Network DLC 

BCS RDS Requester 

BCS RDS Server 

Maximum Link Stations 

4 

4 


Figure 4. DLC Profile 


NETBIOS Profile 

BCS RDS Requester 

BCS RDS Server 

Maximum Link Stations 

4 

4 


Figure 5. NETBIOS Profile 


IEEE 802.2 Profile 

BCS RDS Requester 

BCS RDS Server 

Adapter Number / Version 

0- 16/4 /A 

0- 16/4 /A 

Adapter Address 

xxxxxxxxxxxx 

XXXXXXXXXXXX 

Maximum Link Stations 

12 

41 


Figure 6. IEEE 802.2 Profile 
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BCS configures this profile for use 
with the IBM Token-Ring Network 
16/4 Adapter /A. BCS prompts the 
user to specify if the Universally 
Administered LAN adapter address 
is to be used. If the user specifies 
no, BCS prompts the user for the 
Local LAN adapter address (Lo¬ 
cally Administered Address (LAA) 
of the workstation). If a different 
adapter type is being used, this pro¬ 
file should be modified appropri¬ 
ately. When modifying the default 
values for the Maximum Link Sta¬ 
tions, take into account the previous 
section entitled “DLC Considera¬ 
tions.” 

LU Profile: This profile is used to 
configure an LU that will reside on 
the local workstation (Figure 7). 

The name specified when creating 
the profile will become the local 
LU Alias in this profile. 

BCS creates a profile named LU 1 
for the RDS Requester and LU2 for 
the RDS Server. Both LU1 and 
LU2 are created on a workstation 
configured as an RDS Re¬ 
quester/Server. The appropriate 
Local LU Profile name and Partner 
LU Profile name should be used 
when cataloging the RDS Server 
workstation at the RDS Requester 
workstation. 

Partner LU Profile: This profile is 
used to describe a path to configure 
a partner LU residing on a remote 
workstation (Figure 8). The name 
specified when creating the profile 
will become the partner LU Alias in 
the profile. 

As mentioned earlier, the recom¬ 
mended approach when initially con¬ 
figuring the RDS environment is to 
use a Transmission Service Mode 
profile with a name other than 
SQLLOO or the implicit Transmis¬ 
sion Service Mode. This name 


should be specified in the Partner 

LU Profile. 

• RDS Requester 

BCS will create one partner LU 
profile and will prompt the user 
for the LAN destination address 
(LAA or Universally Adminis¬ 
tered Address of the partner work¬ 
station) to be specified in this 
profile. 

A Partner LU Profile is required 
on the RDS Requester for each 
RDS Server to be accessed. 

These can be created via Commu¬ 
nications Manager’s Advanced 
Configuration Services, using the 
BCS Partner LU as a model pro¬ 
file. When multiple applications 
on the RDS Requester will be ac¬ 
cessing the same RDS Server, the 
Session Limit in the Partner LU 
profile should be increased by 
two for each additional concur¬ 


rent connection. This value 
should be increased by two, be¬ 
cause two Transaction Programs 
are executing on behalf of each 
RDS Requester. 

• RDS Server 

Implicit Partner LU Profiles (indi¬ 
cated by a at the beginning of 
the Partner LU Alias Name) can 
be used at the RDS Server so that 
requests can be accepted from 
any RDS Requester. Explicit 
Partner LU Profiles would re¬ 
quire a profile for each RDS Re¬ 
quester which would gain access 
to this RDS Server. The Server 
has the Partner LU session limit 
set to the maximum in order to 
allow as many Requesters as pos¬ 
sible to gain access. The implicit 
Transmission Service Mode 
*SQLLOO is also used. If 
*SQLLOO is not used, subsys¬ 
tem management allows the view- 



BCS RDS Requester 

BCS RDS Server 

LU Alias 

LU1 

LU2 

LU Name 

LU 1 

LU2 

Default LU 

No 

No 

LU Local Address 

00 

00 

LU Session Limit 

255 

255 

Maximum Number of TPs 

0 

0 


Figure 7. LU Profiles 



BCS RDS Requester 

BCS RDS Server 

Partner LU Alias 

LU2 

*PLU 

Fully Qualified Name 

BLANK.LU2 

BLANK.BLANK 

LU Alias 

LU1 

LU2 

Net. Adap. Numb./ LAA 

XXXXXXXXXXXX 

000000000000 

PLU Session Limit 

1 

255 

Conversation Security 

Yes 

Yes 

CS Verified 

No 

No 

Transmission Service Mode 

SQLLOO 

*SQLLOO 

Initial Session Limits 

LU1ISL 

BLANK 


Figure 8. Partner LU Profiles 
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ing of active sessions, with the 
Partner LU Alias Names appear¬ 
ing as @1000000, @1000001, etc. 

• RDS Requester/Server 

Both LU2 and *PLU profiles are 
created on a workstation config¬ 
ured as an RDS Requester/Server. 

Transmission Service Mode 
Profile: This profile contains ses¬ 
sion characteristics for a specific 
conversation (Figure 9). The name 


Figure 10. Initial Session Limits Profile 


specified when creating the profile 
becomes the Mode name. 

BCS creates a Mode name of 
SQLLOO on the RDS Requester 
and *SQLLOO on the RDS Server. 
Again, the recommended approach 
for initially configuring the RDS en¬ 
vironment is to create a new profile 
with a name other than SQLLOO or 
*SQLLOO. SQLLOO or 
*SQLLOO may be used as the 
model profile for setting up these 
new profiles and then deleted to 


avoid minor inconsistencies from oc¬ 
curring if they are not referenced in 
any Partner LU Profiles. 

Both SQLLOO and *SQLLOO are 
created on a workstation configured 
as an RDS Requester/Server. BCS 
sets the session limit to 1 in the 
transmission service mode profile to 
avoid starting the SNASVCMG 
mode to negotiate the session limit. 

Initial Session Limits Profile: 

This profile contains parameters 
used during Node/Link activation 
(Figure 10). 

BCS creates an Initial Session Lim¬ 
its Profile named LU1ISL. If 
SQLLOO is not utilized, the value 
for automatically started sessions 
can be adjusted to automatically 
start a session during Node/Link ac¬ 
tivation instead of waiting to start 
the session until the application per¬ 
forms a “Start Using” for a particu¬ 
lar database. When using the 
SQLLOO, the initial session limits 
cannot be modified via Communica¬ 
tions Manager’s Subsystem Manage¬ 
ment. 

LU 1ISL is also created on a work¬ 
station configured as an RDS Re¬ 
quester/Server. 

Remotely Attached TPs: These 
are used to describe transaction pro¬ 
grams (TPs) that can be started 
from a remote workstation 
(Figure 11). 

BCS creates two Remotely At¬ 
tached TP Profiles corresponding to 
the TPs provided for RDS on the 
RDS Server. The profile names pro¬ 
vided by BCS for the two RDS 
Transaction Programs are 
SQLAPPLA and SQLSNMGR. The 
profile names can be modified and 
the filespecs should be set with the 
drive letter where Database Man- 



BCS RDS Requester 

BCS RDS Server 

Mode Name 

SQLLOO 

*SQLLOO 

Minimum RU Size 

256 

256 

Maximum RU Size 

1920 

1920 

Receive Pacing Limit 

4 

4 

Session Limit 

1 

255 


Figure 9. Transmission Service Mode Profiles 



BCS RDS Requester 

ISL Profile Name 

LU1ISL 

Minimum Number Cont. Winners Source 

0 

Maximum Number Cont. Winners Target 

0 

Number of Automatically Started Sessions 

0 


BCS RDS 

Server 

TP Profile 

SOLAPPLA Profile 

SQLSNMGR Profile 

Service TP 

Yes 

Yes 

TP filespec 

X:\SQLLIB\SQLCIAA.EXE 

X:\SQLLIB\SQLCNSM.EXE 

First character 

07 

07 

TP name 

6DB 

6SN 

Sync level 

None 

None 

Conv. type 

Basic 

Basic 

Conv. Sec. Req. 

Yes 

Yes 

TP operation 

Non-queued attach started 

Non-queued attach started 

TP rev timeout 

0 

0 

Program type 

Background 

Background 

TP startup 
parms 

BLANK 

BLANK 


Figure II. Remotely Attached TPs 
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ager resides. The RDS TPs are Ser¬ 
vice TPs that take advantage of the 
flexibility provided by the BASIC 
conversation verbs and therefore 
have a BASIC conversation type. 
These TPs run in the background 
and require no user intervention at 
the RDS Server. 

SQLAPPLA is the Server Applica¬ 
tion Agent TP which connects to a 
database at the RDS Server on be¬ 
half of the RDS Requester. 

SQLSNMGR is the Server Node 
Manager TP. The RDS Requester 
starts a second conversation when 
Ctrl+Break is entered to transmit an 
interrupt request to the RDS Server. 
This interrupt request will cause 
RDS at the Server to start the 
SQLSNMGR which “cleans up” the 
currently active database operation 
for that process, rolling it back if 
possible. 

Notice that the RDS TPs are both 
non-queued; therefore, multiple in¬ 
stances of these TPs can be concur¬ 
rently active. Thus, multiple RDS 
Requesters can gain access to an 
SQL Database concurrently. There 
are a couple of ways to limit the 
number of occurrences of the RDS 
TPs. These include setting the Max¬ 
imum number of TPs in the LU pro¬ 
file, or setting the Maximum 
number of concurrent connections 
to a particular database (MAX- 
APPLS configuration parameter) in 
the Database Configuration file. 

The Information and Planning 
Guide for OS/2 Extended Edition 
1 .2, G360-2650, can be used to de¬ 
duce the maximum number of RDS 
Requesters that can attach to an 
RDS Server. 

For example, if you have a 16 MB 
RDS Server and you know that 4.5 
MB of memory is required for the 


base Operating System, CM 
(APPC), and DBM, you will have 
11.5 MB of memory left for RDS 
Requesters. Since 0.18 MB is re¬ 
quired per remote database connec¬ 
tion, the maximum number of 
remote connections is 64. 

The amount of memory required for 
each additional remote database con¬ 
nection will be changed in the next 
version of the OS/2 Information and 
Planning Guide to 0.15 MB. When 
this new number is used, then a re¬ 
calculation yields a maximum of 76 
remote connections. 

These numbers represent the “opti¬ 
mum” amount of memory required, 
and they also represent a medium 
workload. These calculations do 
not include the amount of memory 
required for a DOS Compatibility 
Box, 3270, Gateway, Query Man¬ 
ager, LAN Requester, or any other 
applications executing in the system. 

These numbers strictly represent the 
Database Manager limitations. The 
Communications Manager limita¬ 
tions, such as the maximum number 
of active link stations, should also 
be taken into account. 

User Profile Management and 
Conversation Security: User Pro¬ 
file Management (UPM) is a new 
component of the OS/2 Extended 
Edition 1.2 Base Operating System. 
UPM is utilized to define unique 
user IDs and group IDs (collection 
of user IDs) on each workstation. 
These IDs are allowed access to 
that particular workstation, and are 
then used by other OS/2 Extended 
Edition components to perform 
extra security functions. 

User IDs and group IDs are defined 
by accessing User Profile Manage¬ 
ment Services from the Desktop 
Manager, selecting User Profile 


Management, and selecting Manage 
Users/Group from the Manage pull¬ 
down screen. The user can also ac¬ 
cess UPM via the OS/2 Command 
Prompt by specifying 
"UPMACCTS." 

UPM user IDs are used by DBM to 
prevent unauthorized access to a 
database and its contents. Database 
Manager has new levels of authority 
and privileges replacing the old 
database password. Authorities in¬ 
clude SYSADM and DBADM. 
Privileges are granted to a particular 
user ID, group ID, or to public via 
the GRANT and REVOKE SQL 
statements. 

User IDs are used to logon or logoff 
a user to or from a particular work¬ 
station. When Query Manager is 
started, the user is automatically 
prompted for a user ID and pass¬ 
word. The user may also logon or 
logoff by accessing User Profile 
Management Services from the 
Desktop Manager and selecting 
LOGON or LOGOFF; or via the 
OS/2 Command Prompt by specify¬ 
ing “LOGON userid /P=password” 
or “LOGOFF userid”. 

A user may specify a default user 
ID and password to be utilized at 
the next connection to a particular 
node by specifying “LOGON userid 
/P=password /N=node”. A user can 
also log off a particular node by 
specifying “LOGOFF userid 
/N=node.” 

The default user ID and password 
supplied upon installation is 
’USERID’ and ’PASSWORD'. 

The default group ID defined is 
’GROUPID’ and it contains the user 
ID ’USERID’. 

Because Database Manager security 
is based on UPM IDs, UPM secu¬ 
rity should be used instead of APPC 
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Conversation Security. APPC Con¬ 
versation Security is used to link to 
UPM by setting the first column of 
the first user ID equal to and the 
remaining Conversation Security 
IDs equal to BLANK. 


The RDS Server should contain an 
ID in UPM for each user who will 
access databases residing on this 
workstation. 


Sample Configuration 

Figure 12 is a representation of 
three workstations configured for 
RDS. The configuration for each 
workstation is as follows: one work¬ 
station is an RDS Server 
(SERVER), one workstation is an 
RDS Requester (REQSTR) that will 
need access to two RDS Servers, 
and one workstation is an RDS Re¬ 
quester/Server (REQSRV) which 
has access to both local and remote 
databases. 

SERVER has one local LU defined 
and uses an implicit partner LU in 
order to permit multiple RDS re¬ 
questers to gain access to databases 
residing on this workstation. 

REQSTR has one local LU defined 
with two partner LUs in order to 
gain access to multiple RDS Serv¬ 
ers. PLU1 is associated with 
SERVER and PLU2 is associated 
with REQSRV. 

REQSRV has two local LUs de¬ 
fined. LU1 is utilized as a Re¬ 
quester LU which has a partner LU 
of PLU2 (SERVER). LU2 is used 
as an RDS Server LU with an im¬ 
plicit partner LU in order to permit 
multiple RDS Requesters to gain ac¬ 
cess to databases residing on this 
workstation. 

If SQLLOO is used as the transmis¬ 
sion service mode, then link stations 
associated with Service Access 
Point (SAP) 84 are used. 

Database Manager Structure 

OS/2 Database Manager 1.2 (like 
the other OS/2 Extended Edition 
components) can be installed on any 
logical fixed disk drive by using the 
OS/2 Common Install facility. In¬ 
stallation options provide for the in¬ 
stallation of both Database Services 
and Query Manager, just Database 


SERVER 


LU2 


*PLU 


PU 


SAP 04 


SAP F0 


SAP 84 


I I I I i I I I 


802.5 


802.5 


I I I I 


SAP 04 


SAP F0 


SAP 84 


PU 


LU1 

PLU 1 


PLU2 


REQSTR 


802.5 


I I I I I 


SAP 04 


SAP F0 


SAP 84 


PU 


LU 1 

PLU 2 


LU2 

*PLU2 


REQSRV 


Figure 12. Sample Configuration 
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Services, or Query Manager (which 
requires that Database Services has 
already been installed). The installa¬ 
tion of the RDS components is part 
of the Database Services installa¬ 
tion. Database Manager determines 
which components of Database Ser¬ 
vices to install by the responses 
given by the user during the installa¬ 
tion procedure. For example, the 
question “Will other workstations 
need access to databases on your 
workstation?” allows Database Man¬ 
ager to determine whether or not 
the RDS Server component should 
be installed. 

The SQLLIB subdirectory contains 
Database Manager executables 
along with other necessary informa¬ 
tion such as the Database Manager 
Configuration File, the subdirectory 
containing the Database System Di¬ 
rectory, and the subdirectory con¬ 
taining the Database Manager Node 
Directory. 

During database creation the user 
has the ability to specify a particu¬ 
lar fixed disk drive for the database. 
A new subdirectory is created on 
the fixed disk (volume) specified 
called SQLxxxxx, where xxxxx is a 
number such as 00001 which 
uniquely identifies this subdirectory 
to Database Manager. Another sub¬ 
directory called SQLDBDIR con¬ 
tains the Database Volume 
Directory for this particular fixed- 
disk drive. 

Databases are created locally at the 
RDS Server workstation, and then 
the RDS Requester can access them 
remotely. A database directory can¬ 
not be created remotely. 

The tree diagram in Figure 13 
shows the structure of subdirector¬ 
ies created by Database Manager at 
installation and database creation. 
The X represents any logical fixed- 


disk drive. Database Manager may 
reside on a different logical fixed- 
disk drive than actual databases. 

Node Directories 

When installing OS/2 Database 
Manager 1.2 for RDS, the user is 
prompted to supply a node name or 
workstation name. This node name 
is stored in the Database Manager 
configuration file as Workstation 
Name. Node names are used by 
Database Manager to tie together in¬ 
formation placed in the Database 
Node Directory and System 
Database Directory for a particular 
workstation. In the RDS DOS Re¬ 


quester environment, node names 
are used to identify a workstation to 
NETBIOS. 

The Database Node Directory 
(SQLNODIR) contains information 
such as the Local LU, Partner LU, 
and Mode which reference the LU 
Alias, Partner LU Alias, and Trans¬ 
mission Service Mode profiles re¬ 
spectively. 

When a reference to a particular 
database is made. Database Man¬ 
ager scans the System Database Di¬ 
rectory and determines the entry 
type for that database. If the entry 


X: \ 


SQLLIB 


—SQLxxxxx (Database Services .EXE’s, include files, etc.) 
—QRWxxxxx (Query Manager .BND and .CMD files) 

—SQLSYSTM (Database Manager Configuration File) 


SQLDBDIR 


-SQLDBDIR (System Database Directory) 


SQLNODIR 


—SQLNODIR (Database Manager Node Directory) 


SQLxxxxx 


- Database Files 

-SQLDBCON (Database Configuration File) 


SQLDBDIR 


u 


SQLDBDIR (Volume Database Directory) 


Figure 13. Database Manager Subdirectory Structure 
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type is “remote,” then Database 
Manager looks at the “node-name” 
specified and proceeds to scan the 
Database Node Directory in order to 
determine which communications 
profiles should be used to gain ac¬ 
cess to the remote workstation. 

Entries are made to the Database 
Node Directory when a node is cata¬ 
loged. Interfaces for cataloging a 
node are provided via Query Man¬ 
ager and the Database Services API 
(sqlgcatn, sqlguncn). 

When using RDS, a node must be 
cataloged on the RDS Requester 
workstation. When cataloging the 
node on the RDS Requester, specify 
the Node Name (workstation name 
specified at installation) for the re¬ 
mote workstation. Local LU Profile 
Name, Partner LU Profile Name, 
and Transmission Service Mode Pro¬ 
file name. 


Only users defined as local adminis¬ 
trators or administrators can catalog 
nodes. 

The sample node entry in Figure 14 
uses the BCS default profiles and 
defines a workstation as RDSN01 
(RDS Node 01). 

Database Directories 

There are two types of Database Di¬ 
rectories: System Database Direc¬ 
tory and Volume Database 
Directory. The system directory re¬ 
sides in a subdirectory named 
SQLDBDIR inside the SQLLIB sub¬ 
directory. This directory will exist 
on every type of database worksta¬ 
tion - standalone, RDS Requester, 
RDS Server, or RDS Re¬ 
quester/Server. This directory pro¬ 
vides the information necessary for 
Database Manager to determine if a 
database is local or remote. 


Node Directory Information 

RDS Requester Contents 

Node Name 

RDSN01 

Local LU 

LU 1 

Partner LU 

LU2 

Mode Name 

SQLLOO 

Comment 

Default 

Comment Codepage 

Default 


Figure 14. Sample Node Directory 


Database 

Directory 

Information 

RDS Requester 

RDS Server 

System 

System 

Volume 

Database Name 

SAMPLE 

SAMPLE 

SAMPLE 

Drive 

N/A 

C 

C 

Alias 

SAMP01 

SAMPLE 

SAMPLE 

Entry Type 

REMOTE 

INDIRECT 

HOME 

Comment 

Default 

Default 

Default 

Comment Codepage 

Default 

Default 

Default 

Node Name 

RDSN01 

N/A 

N/A 


Figure 15. Sample Database Directory 


The volume database directory re¬ 
sides on each drive where a 
database is created. It is kept in a 
subdirectory named SQLDBDIR. 
This directory provides the informa¬ 
tion necessary for Database Man¬ 
ager to locate a database on a 
particular drive. 

Both the system and volume 
database directories contain a num¬ 
ber of fields: database name, drive, 
alias, entry type, comment, com¬ 
ment codepage, and node name. 

The entry type field contains a 
value of home, indirect, or remote. 
Home entry type can only exist in a 
volume database directory. Indirect 
and remote entry types can only 
exist in a system database directory. 

A home entry type indicates that the 
database resides on the same drive 
as the volume database directory. 

An indirect entry type indicates that 
the database resides locally and the 
system database directory contains a 
reference to the correct volume 
database directory for that database. 
In the corresponding volume 
database directory entry, the entry 
type for this database will be home. 

A remote entry type indicates that 
the database resides on a remote 
workstation. The node name for 
this database corresponds to a node 
name entry in the Node directory 
which provides the information 
needed by Database Manager to 
gain access to the remote worksta¬ 
tion. 

An entry is made to the System 
Database Directory when a database 
is cataloged. Interfaces for catalog¬ 
ing a database are provided via 
Query Manager and the Database 
Services API (sqlgcatd, sqlguncd). 
The volume database directory does 
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not have an interface, but is main¬ 
tained by Database Manager when 
local databases are created or 
dropped. 

In order to utilize RDS to access a 
remote database, the database must 
be cataloged on the RDS Requester 
as remote. Database Manager will 
take care of cataloging the database 
as local on the RDS Server when 
the database is created and the vol¬ 
ume database directory will contain 
an entry type of home. 

Only users defined as local adminis¬ 
trators or administrators can catalog 
databases. 

The sample database directory in 
Figure 15 shows the different 
Database Directories and the infor¬ 
mation required on both the RDS 
Requester and RDS Server in order 
to gain access to the database re¬ 
motely. The node name specified 
on the RDS Requester ties this 
entry to the previous sample node 
directory entry for the appropriate 
communication information. 

Performance Considerations 

Database Manager contains two con¬ 
figuration files with parameters that 
should be taken into account when 
tuning Database Manager and the 
RDS Environment. 

Database Configuration: The 

Database Configuration File 
(SQLDBCON) contains parameters 
that pertain to resources allocated 
for a particular database. Therefore, 
each database that is created con¬ 
tains its own database configuration 
file. Interfaces for modifying this 
configuration file are provided via 
Query Manager and the Database 
Services API (sqlgeudb). Some of 
the parameters that affect perfor¬ 
mance are: 


• Buffer pool size (buffpage) - The 
buffer pool contains database re¬ 
cords which have been read and 
changed. Records remain in the 
buffer pool until the database is 
no longer in use, a commit is is¬ 
sued, or the space is needed in 
the buffer pool for other records. 
Updated records are then written 
to disk. 

• Sort list heap (sortheap) - This 
area contains private segments al¬ 
located per application program 
for sort buffers for each sort 
(ORDER BY, DISTINCT) in the 
application. A large sort buffer 
improves performance of sorting 
operations. 

Database Manager Configuration: 

The Database Manager Configura¬ 
tion File (SQLSYSTM) contains pa¬ 
rameters that pertain to resources 
allocated across all databases on a 
system. Therefore, only one 
Database Manager configuration 
file exists per workstation, and it is 
stored in SQLLIB. Interfaces for 
modifying the Database Manager 
configuration file are provided via 
Query Manager and the Database 
Services API (sqlgusys). Some of 
the parameters that affect perfor¬ 
mance are: 

• Maximum number of remote con¬ 
nections (numrc) - Used to esti¬ 
mate storage required for CM 
buffers. 

• Communication heap size (com- 
heapsz) - Allocated on the RDS 
Requester and RDS Server for 
each requesting application. Re¬ 
cord blocks are allocated from 
this heap. Whether or not block¬ 
ing is to be used is specified dur¬ 
ing the precompile or bind of an 
application. A block is allocated 
for each cursor that is blocked. 
Record blocking affects perfor¬ 


mance because it reduces net¬ 
work traffic by buffering result¬ 
ing data. Record blocking will 
only occur if specified at pre¬ 
compile or bind, if comheap stor¬ 
age is available, and if a cursor is 
read-only. Because comheap is 
allocated for each requesting ap¬ 
plication, set comheap size for 
the process with the greatest num¬ 
ber of open cursors. 

• Maximum requester I/O block 
size (rqrioblk) - One block (of 
size rqrioblk) is allocated in the 
comheap of the RDS Requester 
when database connection oc¬ 
curs. This block is used for com¬ 
munication between the RDS 
Requester and RDS server. This 
block is freed upon database con¬ 
nection termination. 

Additional blocks are allocated 
for each record blocking cursor 
in the application. The rqrioblk 
value is used to determine the re¬ 
cord block size on both the RDS 
Requester and RDS Server. 

These blocks are freed when the 
associated cursor is closed. 

• Maximum server I/O block size 
(svrioblk) - One block (of size 
svrioblk) is allocated in the com¬ 
heap of the RDS Server when 
database connection occurs. This 
block is used for communication 
between the RDS Requester and 
RDS Server. This block is freed 
upon database connection termi¬ 
nation. 

• RDS heap size (rsheapsz) - Allo¬ 
cated on both RDS Requester 
and RDS Server. It provides a 
workarea containing information 
for managing comheap row 
blocks. One heap is allocated 
per application program on the 
RDS Requester. One heap is allo- 
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cated per remote application pro¬ 
gram on the RDS Server. 

Starting RDS 

The RDS environment is ready for 

utilization once: 

• Appropriate Communications 
Manager configuration files have 
been configured and verified. 

• Database Manager has been con¬ 
figured. 

• Databases have been created and 
cataloged as appropriate. 

• The applications to be executed 
remotely have been bound or are 
dynamically bound during execu¬ 
tion into the RDS Server 
database. 

In an RDS environment, the dis¬ 
tribution of an application differs 
in that a bind file (.BND) or a 
database is not required on each 
workstation. For remote 
database access the database ex¬ 
ists at the RDS Server. .BND 
files may exist at either an RDS 
Requester or an RDS Server, de¬ 
pending on which workstation 
the bind is performed at. Access 
of the application (.EXE) file 
from each requesting workstation 
is necessary. 

• User IDs have been created in 
UPM at the RDS Server (and at 
the RDS Requester if Query Man¬ 
ager is being used), and appropri¬ 
ate privileges have been granted. 


The following steps should be per¬ 
formed on the RDS Server: 

• Start Communications Manager 

• Start the Database Manager by is¬ 
suing the STARTDBM command 
at the OS/2 Command Prompt. 

The following steps should be per¬ 
formed on each RDS Requester: 

• Start Communications Manager 

• Start the Database Manager by is¬ 
suing the STARTDBM command 
at the OS/2 Command Prompt. 
This step is not required if the ap¬ 
plication performs this function. 
Query Manager performs this 
function. 

• Start the application. 

Conclusion 

The SAA relational function pro¬ 
vided by RDS is OS/2 to OS/2 “Re¬ 
mote Unit of Work”. Remote Unit 
of Work allows access to a single 
Relational Database Management 
Systems within a unit of work. Ac¬ 
cess to different Relational 
Database Management Systems 
may be obtained with separate units 
of work. 

Distributed Unit of Work allows ac¬ 
cess to multiple Relational Database 
Management Systems within a unit 
of work and requires a two-phase 
commit. Because OS/2’s APPC 
does not implement Syncpoint, a 
two-phase commit has not been im¬ 
plemented for OS/2 Database Man¬ 


ager. For a description of the differ¬ 
ent SAA Relational Database 
phases, refer to announcement let¬ 
ters for the Distributed Relational 
Data in SAA (288-545) and IBM 
Relational Productivity Family En¬ 
hancements Overview (288-546). 

As access to the other Relational 
Database Management Environ¬ 
ments such as DB2, SQL/DS and 
OS/400 Database Manager is devel¬ 
oped, the objectives of transparent 
access to data, performance, loca¬ 
tion autonomy, system managed in¬ 
tegrity, and security will be 
emphasized. RDS implements these 
objectives through the use of of 
APPC and SQLLOO, node and 
database catalog techniques, and as¬ 
sociation of authorities/privileges 
with UPM user IDs. 
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In OS/2 Database Manager, a “pre¬ 
compiler” is a tool that translates 
SQL statements embedded in the 
code of a high-level language into 
compilable code containing calls 
that permit the program to access 
the Database Manager. The pre¬ 
compiler Application Program¬ 
ming Interface (API) provides a 
way for the programmer to write a 
precompiler to support any high- 
level language. This API extends 
the power of the programming lan¬ 
guages by giving them greater 
database function, and extends 
the accessibility of the Database 
Manager. 

Structured Query Language (SQL) 
is the programming interface for de¬ 
fining and manipulating OS/2 Ex¬ 
tended Edition Database Manager 
data. It is used by embedding SQL 
statements into a program written in 
a high-level language (referred to as 
a “host language”). However, since 
SQL is not a part of any standard 
high-level language, a precompiler 
is needed to translate SQL state¬ 
ments into compilable “host lan¬ 
guage” statements. 

To meet the requirements of each 
particular host language, a separate 
precompiler must be provided for 
each language. OS/2 Extended Edi¬ 
tion 1.1 Database Manager supplies 
a precompiler for the IBM C/2™ 
language. Three additional lan¬ 
guages are supported in OS/2 EE 


1.2: IBM COBOL/2, IBM Pas¬ 
cal/2™, and IBM FORTRAN/2™. 
OS/2 EE also has an application pro¬ 
gram interface (API) to Database 
Manager’s Precompiler Services. 
This enables precompilers to be 
written for any other language - lan¬ 
guages that may be needed for your 
application development, but for 
which IBM has not provided a pre¬ 
compiler. 

A precompiler can be written in any 
high-level programming language, 
and certainly does not have to be 
written in the language that it will 
be processing. The task of 
designing the precompiler will be 
easier if the language chosen sup¬ 
ports string manipulation, pointers, 
dynamic allocation of variables, and 


user-defined data structures. Most 
important, the language used must 
have the capability to call Pre¬ 
compiler Services. 

Process Overview 

The discussion of the precompiler 
API begins with an overview of the 
precompilation process. Then each 
phase of the process and the struc¬ 
tures involved will be covered in 
more depth. 

The function of the Database Man¬ 
ager precompiler is divided into two 
parts so the processing of a host lan¬ 
guage program can be separated 
from the processing of the SQL 
statements embedded within the pro¬ 
gram. These two parts are: 
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• The language-specific pre¬ 
compiler function (hereafter 
called “the precompiler”) 

• Precompiler Services (a set of 
routines provided by Database 
Manager) 

The precompiler first scans the pro¬ 
gram, searching for SQL statements 
embedded in the host language. 
When an SQL statement is found, it 
is “preprocessed,” which means that 
any language-specific matter (such 
as comments), and any host vari¬ 
ables and non-blank white spaces 
(such as carriage returns and line 
feeds) are removed. The statement 
is then passed to Precompiler Ser¬ 
vices. Precompiler Services pro¬ 
cesses the statement, returning the 
completion status to the precompiler 
along with instructions for making 
changes to the original source file. 

After the precompiler has processed 
the original program, a new pro¬ 
gram is produced called the “modi¬ 


fied source.” The original SQL 
statements may remain in the pro¬ 
gram as comments, and code is in¬ 
serted by the precompiler to make 
calls to Database Manager Run-time 
Services. Run-time Services is a 
group of routines that access 
Database Services, the part of 
Database Manager that actually 
builds and modifies databases. All 
SQL statements can be translated 
into some combination of calls to 
Run-time Services routines, which 
will be examined more closely later. 

An access plan and a bind file may 
also be products of the precompila¬ 
tion process, depending on the pre¬ 
compiler options utilized. An 
access plan contains the compiled 
form of the embedded SQL state¬ 
ments and is stored in the database 
specified when the precompiler was 
invoked. There is an access plan as¬ 
sociated with every precompiled 
source module. If an access plan is 
created at precompile time, the ap¬ 
plication can be run only against the 


database specified during pre¬ 
compilation. 

Alternately, the creation of an ac¬ 
cess plan can be deferred and a bind 
file created instead. The bind file 
contains SQL statements and host 
variable definitions from the pre¬ 
compiled program. It is language 
independent, and will permit the ap¬ 
plication to be bound later to other 
databases without recompiling. 

Figure 1 illustrates the flow of the 
precompilation process. 

Division of Tasks 

There are numerous tasks involved 
in turning a database application 
(for example, one containing SQL 
statements) into actions by Database 
Manager against a database. These 
tasks are divided into a number of 
steps, from the application program 
to the Database Manager. 

Application Program: The applica¬ 
tion program must: 

• Contain correct SQL statements 

• Obtain any necessary user infor¬ 
mation 

Precompiler: The responsibilities 
of the precompiler are to: 

• Manage host variables 

• Translate the source file into a 
modified source file in the host 
language, by doing the following: 

— Initially process SQL state¬ 
ments before sending them to 
Precompiler Services, remov¬ 
ing any host language-specific 
matter 



Figure 1. Precompilation Process 


— Include original SQL state¬ 
ments as comments in modi¬ 
fied source 
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— Create any required data struc¬ 
tures 

— Respond to information re¬ 
turned by Precompiler Ser¬ 
vices to construct Run-time 
Services function calls to be in¬ 
serted into modified source 

Precompiler Services: The respon¬ 
sibilities of Precompiler Services 
are to: 

• Validate each SQL statement, 
check authority of users to issue 
the statement, compile it, and 
store it in an access section 
(which will later become part of 
an access plan) 

• Identify the tasks required to 
carry out the SQL statement and 
create a list of tasks called a task 
array (the task array is used by 
the precompiler in building Run¬ 
time Services function calls) 

• Determine how all host variables 
are used and provide a usage 
code for each variable 

• Build either an access plan, 
which is the sum of all the access 
sections; or, if deferred binding is 
chosen, store the processed SQL 
statements in a bind file 

• Pass coded diagnostic informa¬ 
tion to the precompiler 

Run-time Services: Run-time Ser¬ 
vices provides support for communi¬ 
cating with Database Services. Its 
responsibilities are to: 

• Initialize and validate the SQL 
Communications Area (SQLCA) 
and SQL Description Area 
(SQLDA) 

• Modify the input and output 
SQLDA 


• Call Database Services to process 
compiled SQL statements 

• Pass dynamic SQL statements to 
Database Services 

Database Services: Database Ser¬ 
vices responds to calls made by 
Run-time Services, executing sec¬ 
tions of an access plan to make the 
database changes being requested. 

Data Structures 

How is information passed between 
the executing program, the pre¬ 
compiler, Precompiler Services, and 
Run-time Services? Much of it is 
passed using specific standard data 
structures. 

SQLCA: The SQL Communica¬ 
tions Area (SQLCA) is used to send 
diagnostic information from the 
Database Manager to the host pro¬ 
gram. One of the primary pieces of 
information it contains is the 
SQLCODE, an integer return code 
signifying the completion status of a 
function call. It is interpreted as 
shown in Figure 2. 

The rest of the SQLCA contains 
more specific diagnostic informa¬ 
tion, depending on the contents of 
the SQLCODE. 

All Precompiler Services routines 
use the SQLCA, so it must be de¬ 
fined and allocated by the pre¬ 


compiler before calling Precompiler 
Services. The return codes in the 
SQLCA should be checked after 
every Precompiler Services function. 

SQLDA: The SQL Data Area 
(SQLDA) is used to transfer data 
values between Run-time Services 
and the host program at run time. 
The precompiler does not manage 
this structure directly; this task is 
done by Run-time Services. How¬ 
ever, for every host variable found 
in an SQL statement, the pre¬ 
compiler must provide the follow¬ 
ing information for use in the 
SQLDA: 

• SQLTYPE - an assigned number 
that describes the data type of the 
host variable and whether or not 
it can contain nulls 

• SQLLEN - the length of a vari¬ 
able in bytes; or, in the case of 
decimal type, the precision and 
scale 

• SQLDATA - a pointer contain¬ 
ing the address of a variable 

• SQLIND - a pointer containing 
the address of a null indicator 
variable if one is used 

Token Array: The precompiler 
must assign a token ID for each 
host variable. It is a four-byte inte¬ 
ger and must be unique for each 


Code 

Meaning 

0 (zero) 

Successful execution (there may 


be warning conditions) 

Positive 

Successful execution, but with an 


exception condition 

Negative 

Error condition 


Figure 2. SQLCODE 
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host variable. Precompiler Services 
refers to variables using the token 
ID. 

The Token Array is a one-dimen¬ 
sional array of logically paired four- 
byte integers. The first pair is the 


Figure 3. Usage Codes from the Token Array 


Figure 4. Function Flags from the Task Array 


header, which contains both the 
number of pairs available in the 
array for token IDs and the number 
of pairs that actually contain tokens. 
The remaining pairs in the array 
contain the token ID as the first ele¬ 


ment, and a usage code as the sec¬ 
ond element. 

There is a token ID in the array for 
every instance of a variable in an 
SQL statement. It must be filled in 
by the precompiler. The pre¬ 
compiler must also supply the num¬ 
ber of tokens in the array as the 
second element in the header. 

The usage codes are filled in by Pre¬ 
compiler Services after a compile re¬ 
quest. They are listed in Figure 3. 

Task Array: Like the Token 
Array, the Task Array is a one-di¬ 
mensional array of logically paired 
four-byte integers, and the first logi¬ 
cal pair serves as the header. It con¬ 
tains the number of pairs available 
in the Task Array (a value provided 
by the precompiler) and the number 
of pairs being used (a value filled in 
by Precompiler Services after an 
SQL statement is compiled). 

The remainder of the array contains 
the tasks that the precompiler must 
complete. This list of tasks is re¬ 
turned by Precompiler Services 
after it processes an SQL statement. 
The first element is a function flag 
that represents a function the pre¬ 
compiler must perform; the second 
element contains data necessary to 
perform the function. Figure 4 is a 
list of the function flags and the pre¬ 
compiler actions they generate. 

Option Array: The Option Array 
is used by the precompiler to pass 
options to Precompiler Services. It 
contains an eight-byte header fol¬ 
lowed by several pairs of four-byte 
integers. The header contains the 
amount of space allocated for the 
array and the number of options ac¬ 
tually used. The remainder of the 
array contains option information re¬ 
garding date and time format, isola¬ 
tion level, record blocking, and 


Usage Code Meaning 

SQLA_INPUT_HVAR (0) 

Input host variable 

SQLA_INPUT_WITH_IND (1) 

Input host variable with 
indicator variable 

SQLA_OUTPUT_HVAR (2) 

Output host variable 

SQLA_OUTPUT_WITH_IND (3) 

Output host variable with 
indicator variable 

SQLAJNDICATOR (4) 

Indicator variable 

SQLA_INVALID_USE (5) 

Host variable does not match use 

SQLA_USER_SQLDA (6) 

User-defined SQLDA name 

SQLAJNVALIDJD (7) 

Host variable token ID is not valid 


Function Flag 

Action Generated 

SQLA_START 

Generate a call to SQLASTRT. 

SQLA_DECLARE 

Begin or end parsing host variable declara¬ 
tions. 

SQLAJNCLUDE 

Generate code for an SQLCA or SQLDA 

SQLA_ALLOC_INPUT 

Allocate an input SQLDA using SQLAALOC. 

SQLA_ALLOC_OUTPUT 

Allocate an output SQLDA using 

SQLAALOC. 

SQLA_SETS 

Register a host variable using SQL ASETS. 

SQLA_USDA_INPUT 

Register an input user-defined SQLDA. 

SQLA_USDA_OUTPUT 

Register an output user-defined SQLDA. 

SQLA_CALL 

Generate a call to SQLACALL. 

SQLA.DEALLOC 

Generate a call to SQLADLOC. 

SQLA_STOP 

Generate a call to SQLASTOP. 

SQLA_SQLERROR 

Generate code for WHENEVER SQLERROR. 

SQLA_SQLWARNING 

Generate code for WHENEVER 
SQLWARNING. 

SQLA_NOT_FOUND 

Generate code for WHENEVER 
NOT_FOUND. 
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information regarding whether or 
not an access plan and a bind file 
are to be generated. 

Initialization Tasks 

Before the precompiler actually be¬ 
gins to process a source program, it 
must perform several initialization 
tasks. These tasks include: 

• Defining an SQLCA 

• Installing a control-break handler 
so that if the user decides to ter¬ 
minate precompilation by press¬ 
ing Ctrl+Break, the program will 
terminate properly 

• Processing command line argu¬ 
ments, which include the source 
file name, modified source file 
name, bind file name, database 
name, access plan name, and any 
user options 

• Opening the source file for input 
and the modified source file for 
output 

• Preparing the Option Array 

• Calling the Precompiler Services 
routine SQLAINIT to initialize 
the precompilation process 

• Testing the return code from 
SQLAINIT 

• Processing the program ID - a 
string of characters inserted into 
the modified source will be used 
for coordination between the exe¬ 
cutable program and access plan 
at run time 

SQLAINIT is one of four Pre¬ 
compiler Services routines. (The 
other routines are SQLAAHVR, 
SQLACMPL, and SQLAFINI.) 
SQLAINIT initializes the Pre¬ 
compiler Services data structures 


and must be completed before call¬ 
ing any other Precompiler Services 
routines. It accepts as input the ac¬ 
cess plan name, database name, 
password, bind file name (if any) 
and the Option Array. It also issues 
a START USING DATABASE. 

An SQLCA containing any warn¬ 
ings or errors is returned to the pre¬ 
compiler, along with the program 
ID. 



The precompiler 
maintains a list of all 
host variables. 


Processing the Source File 

After initialization has successfully 
completed, the precompiler is ready 
to begin processing the source file. 

It begins by scanning the file, copy¬ 
ing everything verbatim to the modi¬ 
fied source until it encounters an 
SQL statement. When SQL state¬ 
ments are found, there are a number 
of tasks to be performed. All com¬ 
ments, host variables, and non¬ 
blank white spaces (tabs, 
carriage-returns, line-feeds) must be 
replaced by blanks (X’20’) on a 
character-by-character basis. Any 
quoted strings must be recognized 
by the precompiler and left un¬ 
touched. 

Usually, all host variables are de¬ 
clared between BEGIN DECLARE 
SECTION and END DECLARE 
SECTION statements. The pre¬ 
compiler maintains a list of all host 
variables, registering each host vari¬ 
able with Precompiler Services by 
using the call to SQLAAHVR (Add 
Host Variable). The name, length, 
datatype, and token ID assigned to 


the variable are sent as parameters 
to SQLAAHVR. 

When the precompiler identifies 
host variables in an SQL statement 
and replaces them with blanks, it 
must then look up each variable’s 
token ID in its list of host variables, 
and place the token ID in the Token 
ID Array. The colon that precedes 
host variables in SQL statements is 
left in so that Precompiler Services 
can identify the position of host vari¬ 
ables. As a final step in preprocess¬ 
ing the SQL statement, the 
precompiler adds a spare byte, 
which will be used in compiling the 
statement. 

When the statement and the Token 
ID Array are prepared, the pre¬ 
compiler invokes the Precompiler 
Services SQLACMPL (Compile) 
routine. Precompiler Services com¬ 
piles the SQL statement by parsing 
it and determining exactly what 
tasks must be performed to carry 
out the statement. If there are no er¬ 
rors, it stores the statement in a bind 
file (if one is being created) and cre¬ 
ates the Task Array. It also deter¬ 
mines exactly how each host 
variable is being used, and places 
the usage code in the Token ID 
array for each occurrence of a vari¬ 
able. 

The precompiler then checks the 
SQLCODE in the SQLCA for er¬ 
rors or messages. If no errors oc¬ 
curred, the precompiler begins 
checking the task array to see what 
tasks must be performed in the mod¬ 
ified source in order to execute the 
SQL statement. The precompiler 
must then generate code in the host 
language to include the required 
Run-time Services function calls. 

There are eight Run-time Services 
function calls. Each SQL statement 
can be broken down into some com- 
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bination of these calls. They in¬ 
clude: 

• SQLASTRT - starts run-time 
statement execution, and is al¬ 
ways required. SQLASTRT ob¬ 
tains a semaphore to make sure 
thread access is serialized in 
order to enforce synchronization. 

• SQLAALOC - allocates an input 
or output SQLDA. It is used if 
the statement contains host vari¬ 
ables. 

• SQLASETV - used only if the 
statement contains host variables, 
and follows the call to 
SQLAALOC. It initializes fields 
of an SQLDA SQLVAR element. 

• SQLAUSDA - sets a pointer to 
the address of a user-defined 
input or output SQLDA. It is 
used in the execution of dynamic 
SQL statements. 

• SQLASETS - also used to exe¬ 
cute dynamic SQL statements, 
this call sets a pointer to the 
length and address of a host vari¬ 
able used to store the text of the 
statement. 


• SQLACALL - a function that 
calls Database Services with the 
specific access section to exe¬ 
cute. It is the one function that 
actually accesses Database Ser¬ 
vices and is always used for exe¬ 
cuting an SQL statement. 

• SQLADLOC - deallocates 
SQLDAs previously allocated by 
SQLAALOC. 

• SQLASTOP - marks the end of 
the execution of the SQL state¬ 
ment. It releases the semaphore 
originally acquired by 
SQLASTRT. 

After completing processing of the 
source file (or if a fatal error oc¬ 
curs), the precompiler terminates 
Precompiler Services with a call to 
SQLAFINI. Once this call is is¬ 
sued, no other calls can be accepted 
by Precompiler Services until an¬ 
other SQLAINIT is issued. 
SQLAFINI saves or discards the ac¬ 
cess program and bind file, if one 
was created, and returns information 
via the SQLCA, indicating whether 
or not the access program and bind 
file were saved. 


Assuming no errors occurred, the 
modified source file is now com¬ 
pleted and ready to be compiled in 
the host language. 

For additional information on the 
Database Manager precompiler API, 
see the following publications: 

IBM OS/2 Extended Edition VIA 
Database Manager Programming 
Guide and Reference , 90X7772. 

IBM OS/2 Extended Edition VI .2 
Database Manager Programming 
Guide and Reference , S01F-0269. 
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UNION, 

INTERSECT, 

EXCEPT 

Patty Brayton 
IBM Corporation 
Dallas , Texas 

This article is intended as a tuto¬ 
rial for the relational database op¬ 
erators UNION, INTERSECT, and 
EXCEPT. Not only will the theoret¬ 
ical concepts be discussed, but 
also the manner in which these 
functions are implemented in 
OS/2 Extended Edition Database 
Manager. Included in this article 
will be examples of each of the 
operators. 

It is assumed that the reader under¬ 
stands basic relational database con¬ 
cepts, especially relations (referred 
to in this article as “tables”), keys, 
and how the data is stored in a rela¬ 
tional database (attributes and 
tuples, referred to as “columns” and 
“rows” here). 

For instructional purposes, the ta¬ 
bles in Figure 1 are used for each of 
the examples in this article. 

UNION and UNION ALL 

UNION is most commonly used to 
combine the results from two or 
more separate queries that would in¬ 
dividually create a “result table.” 
When the UNION operator is used, 
the result consists of all the rows 
(meeting the criteria of the SELECT 
statement) appearing in any or all of 
the individual result tables. Using 
the UNION operator, two result ta¬ 
bles, T1 and T2, are combined to 
create a new result table that con¬ 
tains the set of all rows in T1 or T2 
(or both) that meet the specified con¬ 
ditions in the initial queries (with 
any duplicate rows eliminated). 


This could, of course, be expanded 
to include more than two tables to 
be UNIONed. Note: In OS/2 Ex¬ 
tended Edition Database Manager’s 
implementation, the tables being 
UNIONed together must SELECT 
an equal number of columns, and 
the corresponding columns must be 
the same type. The columns of the 
UNION table are not given names 
by Query Manager. When Query 
Manager is used to perform the 


query, the column headings are la¬ 
beled “EXPRESSION 1,” “EX¬ 
PRESSION 2,” etc., rather than 
“LASTNAME,” “ID,” and so forth. 

The UNION operator can be repre¬ 
sented by the diagram in Figure 2. 

Notice that the resulting table, repre¬ 
sented by T1 UNION T2, contains 
all the data in both T1 and T2. 


EMPLOYEE 

INFO TABLE 



LASTNAME 

INITIAL 

ID 

DEPT 

BROWN 

E. 

12345 

H57 

BROWNING 

E. 

78342 

J34 

POLK 

J. 

43567 

J34 

BOVER 

D. 

87634 

N76 

JOHNSON 

F. 

85461 

N76 

SMYTHE 

W. 

45342 

J34 

DEPT INFO 

TABLE 



LASTNAME 

ID 

DEPT 

MANAGER 

BROWN 

12345 

H57 

Y 

BROWNING 

78342 

J34 

N 

POLK 

43567 

J34 

Y 

BOVER 

87634 

N76 

Y 

JOHNSON 

85461 

N76 

N 

SMYTHE 

45342 

J34 

N 

PERSINFO 

TABLE 



LASTNAME 

ID 

MARRIED 

NUM_OF_DEPS 

BROWN 

12345 

N 

1 

BROWNING 

78342 

Y 

3 

POLK 

43567 

N 

0 

BOVER 

87634 

Y 

5 

JOHNSON 

85461 

N 

1 

SMYTHE 

45342 

Y 

2 

Note: In all of 

the tables, ID is defined as a character field. 


Figure 1. Example Tables 
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T1 T2 



Figure 2. The UNION Operator 


Here are some examples to help 
clarify how the UNION operator 
works. 

Example 1: The following query 
will display all the last names of em¬ 
ployees who are managers: 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

If this query is run, the following is 
displayed: 

LASTNAME 

BROWN 

POLK 

BOVER 

If a list of all non-married employ¬ 
ees is needed, the following query 
could be used: 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = ' N' 

Running this query would cause the 
following to be displayed: 

LASTNAME 

BROWN 

POLK 

JOHNSON 


Now, the two SELECT statements 
can be UNIONed together to form a 
single query to produce a list of all 
employees that are either managers 
or are not married: 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

UNION 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = 'N' 

the result table would be: 

EXPRESSION 1 

BOVER 

BROWN 

JOHNSON 

POLK 

Note that the items in the result 
table are in alphabetical order. One 
of the consequences of using the 
UNION operator is that to remove 
duplicate rows, the rows in the re¬ 
sult table are sorted in ascending 
order. 

Example 2: Suppose that a query 
is needed to find all the married peo¬ 
ple (in all departments) and all the 
people who work in Department J34 


(married or not). The following 
query performs the desired function: 

SELECT LASTNAME, ID FROM 
EMPLOYEE_INFO 

WHERE DEPT = 'J34' 

UNION 

SELECT LASTNAME, ID FROM 
PERS_INFO 

WHERE MARRIED = 'Y' 


When this query is executed, the re¬ 
sult table is: 


EXPRESSION 1 

BOVER 

BROWNING 

POLK 

SMYTHE 


EXPRESSION 2 

87634 

78342 

43567 

45342 


Example 3: In the previous exam¬ 
ples, the columns that were 
SELECTed were the same in both 
statements joined by the UNION op¬ 
erator. This is not required as long 
as corresponding columns are the 
same data type. For example, 

SELECT LASTNAME FROM PERS_INFO 
WHERE NUM_OF_DEPS > 2 
UNION 

SELECT ID FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

would result in: 

EXPRESSION 1 

12345 

43567 

87634 

BOVER 

BROWNING 


UNION ALL 

Recall that the UNION function 
causes deletion of any duplicate 
rows that would appear as a result 
of the operation. UNION ALL 
does not do this. When UNION 
ALL is used, any duplicate rows 
that occur appear in the final table. 
As a result, the rows in the table are 
not sorted, but rather appear in the 
order in which they were entered 
into the original tables. Consider 
Example 1 again, but with the 
UNION ALL operator this time. 
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SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

UNION ALL 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = 'N' 

This query produces the following 
result table: 

EXPRESSION 1 

BROWN 

POLK 

BOVER 

BROWN 

POLK 

JOHNSON 

Note the duplicates and the lack of 
sorting that occurs with the UNION 
ALL operator. 

INTERSECT 

INTERSECT is another set operator 
that can be used to merge two or 
more tables in a relational database. 
When INTERSECT is used, the re¬ 
sult table consists of rows appearing 
in all of the specified tables. (Re¬ 
call that UNION result tables con¬ 
sist of rows appearing in any or all 
of the specified tables.) In other 
words, the intersection of two ta¬ 
bles, T1 and T2, is the set of all 
rows belonging to both T1 and T2. 
INTERSECT (like UNION) will 
cause any duplicate rows to be elim¬ 
inated from the final result table. 
Note: In OS/2 Extended Edition 
Database Manager’s implementa¬ 
tion, the tables to be INTERSECT- 
ed must SELECT an equal number 
of columns, and the corresponding 
columns must be the same type. 

The columns of the INTERSECT 
table are not given names by Query 
Manager. Again, similar to 
UNION, the column headings are 
displayed simply as “EXPRESSION 
1,” “EXPRESSION 2,” etc., when 
Query Manager is used to perform 
the query. 


The INTERSECT operator can be 
represented by the diagram in Fig¬ 
ure 3. 

The result table (T1 INTERSECT 
T2) contains only those rows con¬ 
tained in both T1 and T2. 

To demonstrate the difference be¬ 
tween UNION and INTERSECT, 
the examples used in the UNION 
section of this article have been 
modified to utilize the INTERSECT 
operator in the following examples: 

Example 4: Recall from the 
UNION example, the query: 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

generates the following result table: 

LASTNAME 

BROWN 

POLK 

BOVER 

The query: 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = ' N' 

generates: 

LASTNAME 

BROWN 

POLK 

JOHNSON 


When the two SELECT statements 
are INTERSECTed, the following 
query is created: 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

INTERSECT 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = 'N' 

which generates the result table: 

EXPRESSION 1 

BROWN 

POLK 

Notice that only the names found in 
both the first and the second result 
tables are included in the INTER¬ 
SECT table, and that they are alpha¬ 
betized. As in UNION, the 
INTERSECT function causes the 
data rows in the result table to be 
sorted in ascending order so any du¬ 
plicate rows can be deleted. There¬ 
fore, each row found in a result 
table generated by the INTERSECT 
operator is unique. 

Example 5: The query: 

SELECT LASTNAME, ID FROM 
EMPLOYEE_INFO 

WHERE DEPT = 'J34' 

INTERSECT 

SELECT LASTNAME, ID FROM 
PERS_INFO 

WHERE MARRIED = ' Y' 

causes the following table to be gen¬ 
erated: 


T1 

xxxxxxxxxx 

YYYYYYYYYY 

ZZZZZZZZZZ 

AAAAAAAAAA 

BBBBBBBBBB 


T2 

AAAAAAAAAA 

BBBBBBBBBB 

CCCCCCCCCC 

DDDDDDDDDD 

EEEEEEEEEE 


T1 INTERSECT T2 


AAAAAAAAAA 

BBBBBBBBBB 


Figure 3. The INTERSECT Operator 
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T1 T2 



Figure 4. The EXCEPT Operator 


EXPRESSION 1 EXPRESSION 2 

BROWNING 78342 

SMYTHE 45342 

Again, notice that the rows found in 
the INTERSECTed table are only 
those that are present in both tables 
generated by the SELECT state¬ 
ments. 

Example 6: Unlike the UNION op¬ 
erator, the columns SELECTed in 
each of the statements INTERSECT¬ 
ed are required to be the same. For 
example, if the following query is 
executed: 

SELECT LASTNAME FROM PERS_INFO 
WHERE NUM_OF_DEPS > 2 
INTERSECT 

SELECT ID FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

Query Manager then displays this 
empty table: 

EXPRESSION 1 


Whereas, the following query: 

SELECT LASTNAME FROM PERS_INFO 
WHERE NUM_OF_DEPS > 2 
INTERSECT 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

generates the non-empty table: 

EXPRESSION 1 
BOYER 


This makes sense because the IN¬ 
TERSECT operator is defined as 
generating only those rows of data 
that appear in both INTERSECTed 
tables. 

EXCEPT 

Given two tables T1 and T2, the 
EXCEPT operator generates a result 
table that consists of all rows in 
table Tl, but not in table T2. That 
is, EXCEPT corresponds to the rela¬ 
tional operator DIFFERENCE. 

Note: When the EXCEPT operator 
is used between two SELECT state¬ 
ments, the two statements must SE¬ 
LECT the same number of columns, 
and the corresponding columns 
must be the same type. The se¬ 
lected column(s) will be given a 
heading of “EXPRESSION 1,” “EX¬ 
PRESSION 2,” etc., (by Query Man¬ 
ager) as when using the UNION or 
INTERSECT operators. 

The EXCEPT operator can be repre¬ 
sented by the diagram in Figure 4. 

The result table represents Tl EX¬ 
CEPT T2 - all the rows contained 
in table Tl, but not contained in T2. 

Example 7: This query generates a 
table that contains all employees 
who are married. 


SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = ' Y' 

The table looks like this: 

LASTNAME 

BROWNING 

BOVER 

SMYTHE 

To generate a list of all non-manag¬ 
ers, use the following query: 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = 'N' 

The generated table is: 

LASTNAME 

BROWNING 

JOHNSON 

SMYTHE 

Now, to find out how many married 
people are non-managers, use this 
query: 

SELECT LASTNAME FROM PERS_INFO 
WHERE MARRIED = ' Y' 

EXCEPT 

SELECT LASTNAME FROM DEPT_INFO 
WHERE MANAGER = 'Y' 

The result: 

EXPRESSION 1 

BROWNING 

SMYTHE 

Notice that the condition has been 
changed in the second SELECT 
statement (from ’N’ to ’Y’). Re¬ 
member that all rows generated by 
the second SELECT statement are 
deleted from the table generated by 
the first SELECT statement to form 
the final result table. To find all the 
non-managers, we want to have a 
table with all managers deleted. 
EXCEPT generates a table in which 
all rows are in the first table but not 
in the second. 

Example 8: This query produces a 
list of all non-married employees 
who work in department J34: 
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SELECT LASTNAME, ID FROM 
EMPLOYEE_INFO 

WHERE DEPT = 'J34' 

EXCEPT 

SELECT LASTNAME, ID FROM 
PERS_INFO 

WHERE MARRIED = 'Y' 

The report generated looks like this: 
EXPRESSION 1 EXPRESSION 2 

POLK 43567 

Example 9: To have a meaningful 
result, the columns in both SELECT 
statements should be the same. The 
rows generated by the second SE¬ 
LECT statement are deleted from 
the rows generated by the first SE¬ 
LECT statement. Consequently, if 
the columns SELECTed are differ¬ 
ent, nothing is deleted from the first 
result table. See the following ex¬ 
ample for clarity: 

SELECT LASTNAME FROM PERS_INFO 
WHERE NUM_OF_DEPS > 2 
EXCEPT 

SELECT ID FROM DEPT_INFO 
WHERE MANAGER = ' Y' 

The table generated by the first SE¬ 
LECT statement is: 

LASTNAME 

BROWNING 

BOYER 


The table produced by the second 
SELECT statement is: 

ID 

12345 

43567 

87634 

Obviously, there are no rows in the 
second table that are also in the first 
table, so nothing is deleted from the 
first table. Therefore, the EXCEPT 
table generated is: 

EXPRESSION 1 

BOVER 

BROWNING 

Notice that in all these examples the 
output is sorted in ascending order 
so any duplicate rows can be de¬ 
leted. 

Additional Information 

For additional information, the fol¬ 
lowing resources are recommended: 

• C. J. Date, An Introduction to 
Database Systems , Volume 1, Ad¬ 
dison Wesley. 

• IBM Operating System/2 Ex¬ 
tended Edition Database Man¬ 
ager SQL Reference 


• IBM Operating System/2 Ex¬ 
tended Edition Database Man¬ 
ager Programming Guide and 
Reference 

• IBM Systems Application Archi¬ 
tecture Common Programming 
Interface Database Reference 
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Writing a 

Database 

Manager 

COBOL/2 

Program 

Chris Jagger 
IBM Corporation 
Dallas, Texas 

This article describes the inter¬ 
face provided for writing IBM 
COBOL/2 applications to gain ac¬ 
cess to the IBM OS/2 EE 1.2 
Database Manager (DBM). It also 
includes a sample of such an ap¬ 
plication. 

An IBM COBOL/2 application pro¬ 
gram interfacing to the OS/2 EE 
DBM follows the same basic for¬ 
mat, with appropriate divisions, as 
any COBOL/2 application program. 

The IDENTIFICATION (spelled 
out) DIVISION is required. The 
name of the program, PROGRAM- 
ID, must be stated here. Optional 
information such as Author, Date 
Written, Date Compiled, and so 
forth, can be included. This infor¬ 
mation is treated as comments by 
the compiler. 


The ENVIRONMENT DIVISION, 
which contains information relating 
to the physical characteristics of the 
machine being used, is not required. 
It may be useful, however, to in¬ 
clude the CONFIGURATION SEC¬ 
TION to document the 
SOURCE-COMPUTER and the OB¬ 
JECT-COMPUTER for the program. 

The DATA DIVISION contains the 
descriptions of all the data used in a 
program. The WORKING-STOR¬ 
AGE SECTION can be thought of 
as the work space for a program. 
Storage is allocated according to the 
data described in this section. The 
LINKAGE SECTION describes ex¬ 
ternal data to be made available to 
the program from another program 
(the calling program), but does not 
allocate the storage. The storage is 
allocated in the calling program. 

The PROCEDURE DIVISION 
holds all executable statements that 
direct the processing logic of a pro¬ 
gram. 

Data is moved between a program 
and an OS/2 database through the 
use of Structured Query Language 
(SQL) and host variables. SQL is 
the language used to access data in 
a relational database. When a pro¬ 
gram contains any SQL statements, 


it must be processed by a pre¬ 
compiler. It is the procompiler that 
replaces the SQL statements with 
the appropriate COBOL/2 function 
calls, thus producing a modified 
source file that is ready to be com¬ 
piled. 

Host Variables 

Host variables are variables refer¬ 
enced in an SQL statement. Just as 
there are specific “types” of data al¬ 
lowed in the columns of a database, 
there are also specific SQL data 
“types” allowed to describe host 
variables. The SQL data types sup¬ 
ported by the COBOL/2 interface to 
OS/2 EE 1.2 Database Manager are 
listed in Figure 1. 

No user-defined data types are al¬ 
lowed. Neither arrays nor the 
FLOAT column type are supported 
in COBOL/2. Level number 77 
may be used interchangeably with 
01 except when declaring VAR- 
CHAR and LONG VARCHAR data 
types. 

Numerics 

When using the PIC clause to de¬ 
fine a numerical host variable, both 
the “S” (signed) and the “9" (num¬ 
ber) must be used. If the ”S” is left 
off, the following error message 


DBM Column Type 

SQL Type 

Description 

COBOL/2 Data Type 

SMALLINT 

500 

16-bit, signed integer 

01 NAME PIC S9(4) COMP-5. 

INTEGER 

496 

32-bit, signed integer 

01 NAME PIC S9(4) COMP-5. 

DECIMAL(p,s) 

484 

Packed decimal 

01 NAME PIC S9(n)V9(m) COMP-3. 

CHAR(n) 

1 <= n <= 254 

452 

Fixed-length character string 

01 NAME PIC X(n). 

VARCHAR(n) 

1 <= n <= 4000 

448 

Varying-length character string 

01 NAME. 

49 NAME-1 PIC S9(4) COMP-5. 

49 NAME-2 PIC X(n). 

LONG VARCHAR 

1 <= n <= 32700 

456 

Long varying-length 

01 NAME. 

49 NAME-1 PIC S9(4) COMP-5. 

49 NAME-2 PIC X(n). 


Figure 1. SQL Data Types Supported 
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will be displayed from the pre¬ 
compiler: “The token ’9’ found in a 
host variable declaration is not 
valid/’ The program will not pre¬ 
compile. 

COMP should also be used as 
shown. COMP-5 differs from 
COMP (or COMPUTATIONAL, 
meaning BINARY format) in that 
the values stored are not limited to 
the number of decimal digits indi¬ 
cated in the PICTURE (PIC) clause, 
but to the largest binary number for 
which the allocated storage has 
space. 

Decimals 

When defining a DECIMAL(p,s), 
the following rules apply: 

Sample: 

01 NAME PIC S9(n)V9(m) COMP-3. 

• The value for ’s’ equals the value 
for’m’ 

• The value for ’p’ equals the 
value for ’n’ + ’m’ 

• The value for’m’ is optional 

• Values for ’n’ and’m’ must be 
greater than or equal to zero (0) 

• Value for ’n’ + ’m’ cannot ex¬ 
ceed 31 

• V denotes the decimal point and 
must be used 

• PACKED-DECIMAL can be 
used instead of COMP-3 

Variable-Length Strings 

A variable-length string consists of 
a collective name, a length item, 
and a value item. See VAR- 
CHAR(n) and LONG VAR- 
CHAR(n) in Figure 1. However, 
when referring to a variable-length 


string in an SQL statement, use the 
collective name. 

VARCHAR(n), LONG VAR- 
CHAR(n), as well as CHAR(n), can 
be used to describe database col¬ 
umns with the FOR BIT DATA at¬ 
tribute. These columns can hold 
binary data or other forms of data 
not used by Database Manager. 

This gives an application, such as a 
graphics package, the ability to 
store and access its data using the 
database. The application could use 
the data for its own purposes, such 
as displaying an image. 

Date, Time and Timestamp 

DATE, TIME and TIMESTAMP 
data types are represented internally 
to Database Manager as a series of 
packed decimal digits. When re¬ 
trieved, Database Services converts 
them to fixed-length character 
strings (Figure 2). 

Null Columns 

The OS/2 EE Database Manager 
has a special way of dealing with 
nullable columns, and it does this 
with null indicators. A null indica¬ 
tor is required for each host variable 
used to hold data from a nullable 
column. The null indicator is al¬ 
ways two-bytes long. 

Example: 

01 NCOLUMN PIC X(5). 

01 NCOLUMN-I PIC S9(2) COMP-5. 

If the null indicator contains a nega¬ 
tive integer, the column value is 


null. If, however, the null indicator 
contains a zero or positive integer, 
the corresponding column value is 
not null. The null indicator and its 
associated host variable act as a 
pair. They do not need to be de¬ 
clared together (as they are in the 
preceeding example), but they must 
be referenced together in an SQL 
statement. Place the null indicator 
variable adjacent to the host vari¬ 
able column field, separated by one 
or more spaces. 

Example: 

EXEC SQL SELECT nullcol INTO 
:ncolumn :ncolumn-i 
END-EXEC. 

Naming Host Variables 

Though it is the precompiler that 
identifies these host variables and 
prepares them for use in exchanging 
data with an OS/2 database, the 
COBOL/2 compiler also sees them, 
so certain rules must be followed in 
naming these variables: 

• Use the correct COBOL/2 syntax 

• Variable names can be up to 30 
characters in length 

• SQL and EXEC are reserved 

• Word FILLER not allowed 

• Hyphens (without spaces) are al¬ 
lowed 


DBM1 Column 

SQL 

Description 

COBOL/2 Data Type 

DATE 

384 

10-byte character string 

01 NAME PIC X(10). 

TIME 

488 

8-byte character string 

01 NAME PIC X(8). 

TIMESTAMP 

392 

26-byte character string 

01 NAME PIC X(26). 


Figure 2. DATE, TIME and TIMESTAMP Data Tvpes 
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Declaring Host Variables 

All host variables need to be de¬ 
clared in an SQL DECLARE SEC¬ 
TION. An SQL DECLARE 
SECTION is simply a group of host 
variable declarations preceded by a 
BEGIN DECLARE SQL statement 
and followed by an END DE¬ 
CLARE SECTION SQL statement. 


Example: 

EXEC SQL 

BEGIN DECLARE SECTION 
END-EXEC. 

01 ID PIC S9(4). 

01 JOB PIC X( 5). 

01 YEARS PIC S9(4) 

C0MP-5. 

01 SALARY PIC S9(7)V9(2) 

COMP-3. 

EXEC SQL 

END DECLARE SECTION 
END-EXEC. 

The following rules apply: 


• End each host variable declara¬ 
tion with a period 


• Figurative constants (ZERO, 
SPACE) not allowed 


• COBOL COPY not supported 

• Follow COBOL/2 continuation 
rules to continue lines or strings 

• Valid clauses allowed: PIC¬ 
TURE, USAGE, VALUE 

• Use X as picture character, S9 
for numeric 

• Standard COBOL/2 comments al¬ 
lowed 

SQL Data Type Summary 

The precompiler determines the ap¬ 
propriate SQL data type when it 
finds a host variable DECLARE 
SECTION. Database Manager uses 
this data type to convert the data ex¬ 
changed between the program and 
Database Services. To avoid 
abends, use the data descriptions in 
the charts provided. 

Database Services Function 
Calls (APIs) 

Besides defining the host variables, 
variables needed for calls to the 


DATA DIVISION. 





77 

SPARE1 

PIC 

9(4) 

COMP-5 

VALUE 0 

77 

DB-LENGTH 

PIC 

9(4) 

COMP-5 

VALUE 6 

77 

SPARE2 

POINTER. 



77 

DATABASE 

PIC 

X (5) 

VALUE 

"SAMPLE" 


Put character 

in 

first 

byte. 


77 

D-USE 

PIC 

9(4) 

COMP-5 

. 

77 

U 

PIC 

X REDEFINES D-USE. 


PROCEDURES DIVISION. 

* Use indicator - S for Shared, X for Exclusive 
MOVE "S" TO U. 

CALL "_SQLGSTRD" USING DATABASE 

SPARE2 
SQLCA 

BY VALUE D-USE 
BY VALUE DG-LENGTH 
BY VALUE SPARE1. 


Figure 3. START USING DATABASE API 


Database Services Application Pro¬ 
gram Interfaces (APIs) must also be 
declared in the DATA DIVISION. 
These variables are not declared in 
an SQL DECLARE SECTION. 

One such call is START USING 
DATABASE. Each program access¬ 
ing an OS/2 database must use this 
call to connect to a particular 
database. Figure 3 shows a sample 
DATA DIVISION declaring the nec¬ 
essary variables when using the 
START USING DATABASE API 
followed by the syntax used to call 
the API from the PROCEDURES 
DIVISION. 

Each Database Services function 
call should be preceded with two un¬ 
derscores. Then the compiler uses 
fully segmented addresses when 
passing “by reference” parameters. 
However, Query Manager will ac¬ 
cept function calls without the un¬ 
derscores. 

For each DBM API, the OS/2 EE 
1.2 Database Manager* s Program¬ 
ming Guide and Reference , Volume 
If S01F-0269, lists the variable in¬ 
formation as required, as well as the 
syntax for applications executing in 
the OS/2 PC environment and in the 
DOS environment (APIs supported 
by the DOS Database Requester). 

When defining variables for the 
DBM APIs, all pointers are four- 
bytes long, and all two-byte nu¬ 
meric variables used as value 
parameters must be declared as 
COMP-5. 

A list of the various APIs supported 
in COBOL/2 for both an OS/2 EE 
1.2 environment and a DOS 
Database Requester environment is 
given in Figure 4. 
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DBM Include Files 

The last items in the DATA DIVI¬ 
SION to focus on are the DBM In¬ 
clude Files. These files contain 
necessary function definitions and 
error codes for the various environ¬ 
ment, utility and miscellaneous com¬ 
mands, as well as system constants. 
The actual files used in a program 
will depend on the functions used in 
that program. Figure 5 describes 
each file. 

There are two ways to define these 
DBM structures in an application: 
COPY or EXEC SQL INCLUDE 
statement. A COPY statement can 
be used on any of these files; an IN¬ 
CLUDE statement can be used only 
on SQLDA/SQLCA. Deciding 
which method to use for 
SQLDA/SQLCA depends on when 
the program needs the information. 
An EXEC SQL statement is re¬ 
solved at precompile time while the 
COPY statement is resolved at com¬ 
pile time. Use the COPY statement 
to include the other files. 

Procedure Division 

The PROCEDURE DIVISION is 
where data is processed and manipu¬ 
lated. It is here that executable 
SQL statements are embedded into 
COBOL/2 code and calls are made 
to the Database Services APIs. 

Some rules to keep in mind here are: 

• Precede function calls with two 

underscores (_). 

• Host variables in an SQL state¬ 
ment must begin with a colon (:). 

• Statements can begin in Area A 
(8-11) or Area B (12-72) Note: 

To follow Systems Application Ar¬ 
chitecture™ (SAA™) guidelines, 
use Area B. 


Environment 

OS/2 

RDS 

Routines Supported 

Environment 

DOS Requestor 

Start/Stop Database Manager 

X 


Start/Stop Using Database 

X 

X 

Database Restart 

X 

X 

Log On/Off 

X 

X 

Install Signal Handler 

X 


Interrupt 

X 

X 

Create/Drop Database 

X 


Change Database Comment 

X 

X 

Catalog/Uncatalog Database 

X 

X 

Catalog/Uncatalog Node 

X 


Migrate Database 

X 

X 

Open/Close Directory Scan 

X 

X 

Open/Close Node Scan 

X 


Get Next Directory Entry 

X 

X 

Get Next Node Entry 

X 


Dereference Address 

X 

X 

DB Appl. Remote Interface 

X 

X 


Utility 

OS/2 

RDS 

Routines Supported 

Environment 

DOS Requestor 

Backup/Restore 

X 


Import/Export 

X 

X 

R unstats 

X 

X 

Reorganize Table 

X 

X 

Update DBM/DB Config 

X 


Reset DBM/DB Config 

X 


Return Copy DBM/DB Config 

X 


Collect Database Status 

X 


Get User Status 

X 


Get Next DB Status Block 

X 


Free DB Status Resources 

X 


Get Administrative Authority 

X 

X 

Get Address 

X 

X 


Miscellaneous 

OS/2 

RDS 

Routines Supported 

Environment 

DOS Requestor 

Bind 

X 


Retrieve Error Message 

X 

X 


Figure 4. Supported APIs 
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SQL - 
SQLENV - 
SQLUTIL - 
SQLCODES 


Contains all the system constants for the DBM, SQLCA and SQLDA. 

Contains structures, constants, and return codes for the DBM environment commands. 
Contains structures, constants, and return codes for the DBM utility commands. 

Defines the possible values that can be returned to the SQLCODE variable in the SQLCA. 


SQLCA - Defines the SQL Communications Area structure. This structure holds information about the most 
recently executed function call or SQL statement. The value of the SQLCODE variable in the 
SQLCA is used to determine whether an SQL statement or function call executed successfully or 
not. This file should be included in all programs and the SQLCODE should be checked after each 
statement or call: 


SQLCODE = 


0 


positive 

negative 


100 


Successful execution 
Successful, but with a warning 
Error condition 
Not found 


The following sample shows how to evaluate the value of the SQLCODE to determine what action to 
take if 1) the SQL statement completed successfully, 2) the end of the table is reached, or 3) any 
other value appears: 

EVALUATE SQLCODE WHEN 0 CONTINUE 

WHEN 100 PERFORM MOVE "1" TO END-OF-TABLE-SW 
GO TO 100-EXIT END-PERFORM 
WHEN OTHER PERFORM DBERROR 

END-EVALUATE. 

SQLDA - Defines the variable-length SQL DESCRIPTOR AREA structure. This structure is used to pass data 
between Database Services and the application program. It is most often used with Dynamic SQL 
where the SQL statement is not fully known when the application is written or the objects referenced 
by the SQL statement do not exist at precompile. 

The information in the SQLDA depends on its use. In a PREPARE and DESCRIBE statement, the 
SQLDA provides information to an application about the prepared statement. In an OPEN, EXE¬ 
CUTE, and FETCH statement, the SQLDA describes the host variables that can be used to allocate 
the storage needed. 

DSQCOMM - This structure is required when a program uses the Query Manager Callable Interface and provides 
two services. It receives return code, reason code and message ID information from Query Man¬ 
ager (much like the SQLCA structure). Each call must check the DSQ_RETURN CODE to deter¬ 
mine the success of the call: 


0 = Successful execution 
4 = Successful execution, but with a warning 
8 = Command did not execute correctly 
16 = Severe error, QM session terminated 


The DSQCOMM also provides a working storage area for the Query Manager Callable Interface. A 
DSQCOMM structure is necessary for each QM session started. 


Figure 5. Database Manager Include Files 
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• SQL statements follow the same 
line continuation rules as 
COBOL/2. However, the key¬ 
word pair EXEC SQL must be 
on one line. 

Precompiling the Program 

Once the program is written, use 
SQLPREP to precompile, making 
certain to include the file extension 
for COBOL (.SQB) on the com¬ 
mand line. In this step, the pre¬ 
compiler converts the SQL 
statements into a form that can be 
compiled and turns each SQL state¬ 
ment into a comment. The pre¬ 
compiler creates a new file with a 
.CBL extension. 

The program can be bound to the 
database at this time, or the bind 
can be deferred. If the program is 
bound during precompile, it can be 
bound to only one database. If, 
however, the bind is deferred, the 
program can later be bound to more 
than one database. Another advan¬ 
tage to deferring the bind is that 
when it is time to create a new ac¬ 
cess plan, after a REORG and 
RUNSTATS, only the bind will 
need to be redone. Otherwise an ap¬ 
plication would need to be pre¬ 
compiled, compiled and linked 
again. 

Example: 

SQLPREP INCREASE.SQB SAMPLE /B 

This command precompiles the pro¬ 
gram INCREASE deferring the bind 
(see Note 1 at the end of this arti¬ 
cle). Note that even though the bind 
is being deferred, the database name 
is still required or the precompile 
will not be successful. This exam¬ 
ple creates a .CBL and a .BND file 
with the name INCREASE. 


Compiling and Linking the 
Program 

After the precompile, the applica¬ 
tion may be compiled using any nec¬ 
essary compiler directives. For 
applications using the COBOL/2 in¬ 
terface to the OS/2 EE Database 
Manager, using the /NOTRUNC op¬ 
tion is suggested (see Note 2). This 
option takes advantage of the full 
range of COMP-5 integers. This 
step creates the object file. The 
compiler produces a new file with a 
.OBJ extension. 

Example: 

PCOBOL INCREASE.CBL /NOTRUNC 

This command compiles the pro¬ 
gram INCREASE and creates a 
.OBJ file with the name IN¬ 
CREASE. 

The next step is to link the object 
file with the proper libraries. To 
link a program to run under OS/2, 
the PCOBOL and DOSCALLS li¬ 
braries must be used. Three librar¬ 
ies provided by Database Manager 
may also need to be included: 
SQL_DYN.L1B (dynamic). 


SQL_STAT.LIB (static), and/or 
DSQCI.L1B (Query Manager Call¬ 
able Interface). /NOP is a required 
option when linking a program to 
run under OS/2 (see Note 2). Using 
this option ensures that the link com¬ 
mand will not try to pack neighbor¬ 
ing logical code segments into one 
physical segment. 

If an application consists of several 
modules, there are two ways to link 
it: as a single .EXE file, or as a 
main .EXE that calls one or more 
.DLL (Dynamic Link Library) files 
at runtime. Linking produces the 
executable program module; an ex¬ 
ample is shown in Figure 6. 

Binding The Program 

If binding was deferred, the pro¬ 
gram .BND file needs to be bound 
to a database before it will execute 
(see Note 1 on the next page). 

Example: 

SQLBIND INCREASE.BND SAMPLE 

This binds the INCREASE.BND 
file to the SAMPLE database. 


Example: 

LINK INCREASE.OBJ 


This command links the program INCREASE with all the libraries listed. 
The three commas mean that it will produce a .EXE file (the executable 
module) and a .MAP file (a list of the segments of the program and groups) 
with the same name as the .OBJ file (INCREASE). The “response” infor¬ 
mation (surrounded by the box) can be stored in a file of any name. To use 
it with the link command, it must be preceded by an “at” sign (@). If this 
information was saved in a file called DBM.LNK, the link command would 
look like this: 

LINK INCREASE.OBJ @DBM.LNK 


Figure 6. Linking a Program 


.,,\PC0B0L\PCOBOL.LIB+ 
\0S2\DOSCALLS.LIB+ 
\SQLLIB\SQL_STAT.LIB+ 
\SQLLIB\SQL_DYN.LIB+ 
\N0P; 
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If there is more than one .BND file 
to be bound to the database, a file 
needs to be created that lists the 
bind file names. To use this file 
with the SQLBIND command, it 
must be preceded by an “at” sign 
(@). 

Sample Program 

Figures 7a, 7b and 7c show a pro¬ 
gram that uses the COBOL/2 inter¬ 
face to access information in the 
OS/2 EE Database Manager 
database “SAMPLE” to increase by 
five percent the salary of employees 
who have been with the company 
more than 10 years. This program 


is meant for illustrative purposes 
only. Comments are indicated with 
asterisks. 

Note 1: Several other options can 
be used with the SQLPREP and the 
SQLBIND commands. These are 
documented in the IBM OS/2 1.2 
EE VI .2 Commands Reference man¬ 
ual, S01F-0282. 

Note 2: Several other options can 
be used with the PCOBOL and 
LINK commands. These are docu¬ 
mented in the IBM COBOL/2 Com¬ 
pile , Link and Run manual, 
84X1673. 
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********************************* 

********************************* 

IDENTIFICATION DIVISION. 
PROGRAM-ID. INCREASE. 


********************************* 

* DATABASE 

OS/2 EE SAMPLE 

* ENVIRONMENT 

STANDALONE 

* PURPOSE 

UPDATE STAFF TABLE: 

* 

INCREASE SALARY BY 5% THOSE EMPLOYEES WHO 

* 

WHO HAVE BEEN HERE MORE THAN 10 YEARS. 

* DEPENDENCIES 

THE SAMPLE DATABASE PROVIDED WITH OS/2 EE 

* 

MUST BE INSTALLED. TO INSTALL TYPE: SQLSAMPL 

* COMPLIER OPTIONS 

/NOTRUNC /ANS85 

********************************* 

********************************* 

DATA DIVISION. 


********************************* 

WORKING-STORAGE SECTION. 


********************************* 

COPY SQLCA. 

COPY SQLCODES. 


********************************* 

* Fields used for Start Using Database 

********************************* 

77 D-USE 

PIC 9(4) COMP-5 

77 U REDEFINES D-USE 

PIC X. 

77 SPARE2 

POINTER. 

77 DATABASE-NAME 

PIC X( 8 ) VALUE "SAMPLE”. 

77 SPARE1 

PIC 9(4) COMP-5 VALUE 0. 

77 DB-NAME-LENGTH 

PIC 9(4) COMP-5 VALUE 6. 


Figure 7a. Sample DBM COBOL/2 Program 
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* Fields used to Retrieve Error Message 
*********************************** 


77 

BUFFER-SIZE 

PIC 

9(4) 

COMP-5 

VALUE 

512 

77 

LINE-WIDTH 

PIC 

9(4) 

COMP-5 

VALUE 

0 . 

77 

BUFFER 

PIC 

X( 512 

). 




*********************************** 

*********************************** 

PROCEDURE DIVISION. 

* Install signal handler to handle CRTL-BREAK 

*********************************** 

CALL "_SQLGISIG” USING SQLCA. 
*********************************** 

* See START-DB for start using database 

*********************************** 

PERFORM START-DB. 
********************************* 

* Update the appropriate rows 

*********************************** 

EXEC SQL 

UPDATE STAFF 

SET SALARY - SALARY + (SALARY * .05) 
WHERE YEARS > 10 
END-EXEC. 

*********************************** 

* Check the SQLCODE for errors 

EVALUATE SQLCODE WHEN 0 CONTINUE 

WHEN OTHER PERFORM DBERROR 

END-EVALUATE. 

*********************************** 

* Stop using the database 

CALL “_SQLGSTPD” USING SQLCA. 

GOBACK. 

*********************************** 

* Start Using Database 
*********************************** 

START-DB. 

*********************************** 

* Use Database in Shared Mode 
*********************************** 

MOVE “S” TO U. 

CALL “_SQLGSTRD” USING DATABASE - NAME 

SPARE2 

SQLCA 

BY VALUE D-USE 
BY VALUE DB-NAME-LENGTH 
BY VALUE SPARE1. 


Figure 7b. Sample DBM COBOL/2 Program 
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*********************************** 

* Look to see if database needs to be Restarted 


EVALUATE SQLCODE WHEN 
WHEN 
WHEN 

END-EVALUATE. 

*********************************** 
* Restart database if necessary 


RESTART. 

CALL “_SQLGREST” USING 


EVALUATE SQLCODE WHEN 
WHEN 

END-EVALUATE. 


0 CONTINUE 

-1015 PERFORM RESTART 
OTHER PERFORM DBERROR 


DATABASE-NAME 

SPARE2 

SQLCA 

BY VALUE DB-NAME-LENGTH 
BY VALUE SPARE1 
0 PERFORM START2 
OTHER PERFORM DBERROR 




START2. 
CALL 


_SQLGSTRD” 


EVALUATE SQLCODE 


END-EVALUATE. 


USING DATABASE-NAME 
SPARE2 
SQLCA 

BY VALUE D-USE 
BY VALUE DB-NAMELENGTH 
BY VALUE SPARE1 
WHEN 0 CONTINUE 
WHEN OTHER PERFORM DBERROR 




* Display error # 


DBERROR. 

DISPLAY “SQL ERROR, SQLCODE « 


"SQLCODE. 


* Retrieve Error Message and Display it 

CALL “_SQLGINTP” USING BUFFER 

SQLCA 

BY VALUE LINE-WIDTH 
BY VALUE BUFFER-SIZE. 
DISPLAY “SQL ERROR MESSAGE = "BUFFER. 

GOBACK. 


Figure 7c. Sample DBM COBOL/2 Program 
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Database 

Manager 

Programming 

with 

Procedures 

Language 

2/REXX 

Jeffrey W. Fisher 
IBM Corporation 
Dallas , Texas 

Procedures Language 2/REXX is 
a powerful OS/2 Extended Edition 
Version 1.2 tool for creating pro¬ 
grams utilizing the Database Man¬ 
ager. The Database Manager and 
Query Manager interfaces for Pro¬ 
cedures Language covered in this 
article provide the reader with 
basic knowledge and examples of 
writing programs to create busi¬ 
ness applications and database 
management tools. Several sam¬ 
ple programs illustrate each inter¬ 
face. 

Procedures Language 
Overview 

Procedures Language 2/REXX is a 
powerful structured programming 
language that is included with OS/2 


Extended Edition Version 1.2. It is 
designed for ease of use with very 
English-like syntax. Examples of in¬ 
structions are SAY, PULL, and IF- 
THEN-ELSE. SAY and PULL are 
used respectively to display charac¬ 
ters to the screen and to read charac¬ 
ters from the screen. Several 
commands are included for struc¬ 
tured programming. 

Procedures Language has a free- 
format syntax. One or more instruc¬ 
tions can span multiple lines, start 
in any column, and use mixed 
(upper and lower) case. A good pro¬ 
gramming style uses these tech¬ 
niques to enhance readability. 

Procedures Language includes 
many built-in functions to save 
programmer’s time. Several have 
very powerful string-parsing capabil¬ 
ities. Others deal with data format¬ 
ting. 

One important feature of Procedures 
Language is that all variables are 
considered typeless. All data is 
treated as character strings, although 
math can be performed on any vari¬ 
ables that contain valid numerics. 
Designers of highly numeric-inten¬ 
sive applications should consider 
the specific capabilities of Proce¬ 
dures Language when choosing the 


most appropriate language for each 
part of an application. 

In addition, there is no need to pre¬ 
declare variables (as would be done, 
for example, in a COBOL working- 
storage section); as soon as these 
variables are referenced in the pro¬ 
gram, they are added to the Proce¬ 
dures Language’s variable pool. A 
variable pool is a table maintained 
internally by Procedures Language. 
It identifies all known variables and 
their values. This ease of definition 
makes it particularly easy to use the 
powerful database and dialog inter¬ 
faces available to Procedures Lan¬ 
guage users. 

Procedures Language contains a va¬ 
riety of tracing options for run-time 
debugging. The TRACE facility 
can be used to display each line of 
the program as it executes. 

Procedures Language is particularly 
suited to: 

• Command Procedures 

• Application Driver 

• Application Programming 

• Structured Query Language 
(SQL) Statement Prototyping 
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• Application Prototyping 

• Database Administration Tools 

Command Procedures 

Command procedures (.CMD files), 
as used in previous versions of 
OS/2, are still available. However, 
in any situation where a command 
file would be used in OS/2 Ex¬ 
tended Edition, a Procedures Lan¬ 
guage program can be substituted. 
This gives users significant new ca¬ 
pabilities and flexibility. 

Both Procedures Language pro¬ 
grams and command procedures use 
a “.CMD” extension. Procedures 
Language programs are differenti¬ 
ated from OS/2 command proce¬ 
dures because its a Procedures 
Language requirement that the first 
line begins with a comment. Proce¬ 
dures Language is not supported for 
DOS, DOS Compatibility Box, or 
OS/2 SE users. 

OS/2 optionally runs a command 
procedure at boot time named 
STARTUP.CMD. Users gain addi¬ 
tional flexibility by using Proce¬ 
dures Language to write this 
procedure. 

Application Driver 

Procedures Language can be used 
as a front end for an application and 
as a streaming tool for individual ap¬ 
plication programs. For example, a 
Procedures Language program 
could be used to automatically 
download host files, import them to 
the Database Manager, run an appli¬ 
cation program, and then check its 
return codes or handle any excep¬ 
tional conditions. 

Application Programming 

Procedures Language can be used 
for business application program¬ 
ming. It can format output reports. 


and can use both Query Manager 
and Dialog Manager as presentation 
interfaces. Because Procedures Lan¬ 
guage programs contain typeless 
variables, it may not always be suit¬ 
able for applications requiring com¬ 
plex numerical calculations. A 
higher-level language should be con¬ 
sidered depending on application re¬ 
quirements. 

Application Prototyping 

If the programmer has decided to 
use a higher-level language, the Pro¬ 
cedures Language can still be used 
during development for prototyping 
the application. Simple screen 
flows and representative data could 
be created easily and demonstrated 
to end users. End users could then 
approve the application flow earlier 
in the development cycle. Most or 
all of the SQL, Query Manager com¬ 
mands, and any Dialog Tag Lan¬ 
guage statements written for the 
prototype could then be reused in 
the actual application code. 

Database Administration 
Tools 

Procedures Language supports 
nearly all of the Database Manager 
API calls. A complete list of sup¬ 
ported API calls is available in the 
OS/2 Extended Edition Version 1.2 
Database Manager Programming 
Guide and Reference (S01F-0269). 
Procedures Language offers a partic¬ 
ularly convenient means of housing 
these calls, with much simpler syn¬ 
tax requirements than higher-level 
languages. 

Implications 

The implications of some of these 
features need to be considered by 
the application designer. In terms 
of application programming to the 
Database Manager, Procedures Lan¬ 
guage differs from higher-level lan¬ 
guages in the ways that code is 


developed and prepared for execu¬ 
tion. Because Procedures Language 
programs run interpretively, com¬ 
piles, links and binding to the 
Database Manager are not sup¬ 
ported. During development, the 
programmer can edit a program in 
one window, save it, and immedi¬ 
ately run it in another window. 

Procedures Language programs sup¬ 
port only dynamic SQL. Therefore, 
a Database Manager Access Plan is 
not used. This must be taken into 
consideration if the application has 
performance requirements that an 
access plan would be required to 
support. 

Procedures Language 
Variables 

To understand how the various inter¬ 
faces communicate with Procedures 
Language, it is necessary to review 
basic rules of Procedures Language 
variables. 

Each Procedures Language program 
has its own unique pool of vari¬ 
ables. These variables do not need 
to be declared unless it is necessary 
to assign a value to them before 
they are used. The following state¬ 
ment both declares variable STMT 
and assigns a value to that variable 
for later use: 

STMT = “Select * from STAFF” 

Variable values can also be entered 
from the screen. The following 
statement asks the user for a 
database name to be used and as¬ 
signs it to the variable named 
DBNAME: 

say “Please enter the DB name” 
pull DBNAME 

With compound variables, multidi¬ 
mensional arrays may be created. 

For example, the variable AN¬ 
SWERS is one-dimensional. How- 
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/* 

Name 

COMP ILE.cmd 

*/ 

/* 

PIatform 

OS/2 Extended Edition 1.2 

*/ 

/* 

Purpose 

Performs a PCOBOL compile 

*/ 


say 'Enter the name of your program' 
pull progname 


Ask the user for the program name to compile. PULL 
the name of the program. The variable PROGNAME 
now contains the program name. 


say 'Beginning compile of' progname 


Display a message stating that the compile is beginning. 


address cmd 'PCOBOL' progname 


Pass the PCOBOL command to the OS/2 command pro¬ 
cessor, with the program name. 


say 'Compile complete’ 


When the compile is complete, notify the user. 


exi t 


The Procedures Language EXIT command ends the pro¬ 
gram and returns control to OS/2. 


Figure 1. A COBOL Compile Utility. 


ever, ANSWERS. 1 is the first entry 
of the array ANSWERS, AN¬ 
SWERS.2 is the second entry, etc. 
Some of the following sample pro¬ 
grams use compound variables to re¬ 
ceive data from the Database 
Manager utilities. 

External Command Passing 

Commands can be passed to envi¬ 
ronments external to the Procedures 
Language with the ADDRESS com¬ 
mand. The following command 
passes a “DIR” command to the 
OS/2 command processor: 

ADDRESS CMD *DIR' 

Some commands, such as the Proce¬ 
dures Language EXIT, are common 
to both Procedures Language and 
external environments. EXIT is 
used to end a Procedures Language 
program. Passing this command to 
OS/2 also causes the program to 
end and causes the window to close 
if running in a window. 

Figure 1 shows an example of using 
Procedures Language to create a 
simple utility to assist in a repetitive 
task. The sample program asks the 
user for a program name and then 
passes it to the COBOL/2 compiler. 


The code is in the left column: the 
explanation of the code is in the 
right column. In some later exam¬ 
ples where it is not necessary to 
show all of the code in a sample 
program, single periods represent 
lines of code not shown. 

All Procedures Language programs 
are required to begin with a com¬ 
ment. Comments begin with /* and 
end with */. This signifies to OS/2 
that it will process a Procedures 
Language program, rather than a 
Command procedure. 

Complex commands with multiple 
parameters can be simplified to the 
end user by writing a Procedures 
Language program to collect, edit, 
and pass the commands in proper se¬ 
quence. Figure 1 could be easily 
modified to perform a precompile, 
compile, link, and bind for a 
COBOL/2 program. Procedures 
Language can even help the user 
with the relative complexities of 
high-level language programming. 

Interface Registration 

Interfaces external to Procedures 
Language, including Database Man¬ 
ager and Query Manager, must be 


identified to the Procedures Lan¬ 
guage command processor before 
they can be used. This in known as 
registering an interface. Each inter¬ 
face can be registered and dropped 
in each Procedures Language pro¬ 
gram or can be accomplished via 
the STARTUP.CMD at boot time. 
DLL modules associated with these 
interfaces require system memory 
even when not in use. Under some 
circumstances, it may be desirable 
to drop the interfaces when they are 
not needed. 

The systems designer must decide 
to register functions consistently ei¬ 
ther at boot time with 
STARTUP.CMD or in each pro¬ 
gram requiring them. If performed 
in each individual program, then the 
designer must ensure that these nec¬ 
essary functions are not dropped 
when they may be in use by another 
user. Therefore, it may be advis¬ 
able to register all functions at boot 
time only. 

The examples presented in this arti¬ 
cle all register their interfaces in 
STARTUP.CMD. Note that the 
STARTUP.CMD also executes a 
STARTDBM (start Database Man- 
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ager). Starting and stopping 
Database Manager is similar to reg¬ 
istration because another application 
may be concurrently using Database 
Manager. 

Figure 2 illustrates an example of a 
STARTUP.CMD showing the Proce¬ 
dures Language commands used to 
register the interfaces required by 
the sample programs. 

Database Manager Interface 

The Database Manager interface 
uses a communication area known 
as the SQLCA to pass information 


contained within variables to and 
from the Database Manager. Sev¬ 
eral SQLCA and other variables are 
provided for the user by the inter¬ 
face (Figure 3). 

Figure 4 shows use of some of the 
variables provided in the communi¬ 
cations area to handle exceptions. 

API Calls Interface 

The SQLDBS interface processes 
Database environment and utility 
routines. It operates on a call/return 
basis, whereby control is passed to 
Database Manager to perform a 


function. When Database Manager 
finishes, control is passed back to 
the program with return-code infor¬ 
mation. 

API call syntax is: 

CALL SQLDBS ’character-string’ 

’Character-string’ can be any one of 
a number of supported API calls. 
The character string is delineated by 
quotes and can span multiple lines. 
A multiple line command string will 
be discussed in a later example. 


/* Name : STARTUP.cmd */ 

/* Purpose : boot-time startup functions */ 

/* Platform : OS/2 Extended Edition 1.2 */ 

/* */ 


say 'STARTUP Processing' 

say 'Register Procedures Language 

SQL functions' 

The SAY command displays a message to the screen. 
Because the operating system starts a window for 
STARTUP.CMD to run in, messages are displayed in 
that window as the Procedures Language program exe¬ 
cutes. This keeps the user informed of a program’s prog¬ 
ress. 

rcy - RxFuncadd('SQLEXEC’, 'SOLAR', 

'SQLEXEC') 

The syntax for registering the Procedures Language SQL 
interface. 

rcy = RxFuncaddC'SQLDBS’ , 'SOLAR' 

say 'Register QMCI function' 

DSQRGSTR 

say 'Start Database Manager' 

, 'SQLDBS') 

The syntax for registering the Procedures Language 

Database Manager API interface. 

The command that registers the Query Manager Callable 
Interface. A command is provided for this, although the 
other method is also available. 

STARTDBM 


This step starts the Database Manager. This is handled 
as in OS/2 Extended Edition Version 1.1. 

say ' ' 

say ’>>> STARTUP command complete 

say ' ' 

ADDRESS CMD 'EXIT' 

<«' 

This step displays a message that the program has com¬ 
pleted, again for the convenience of the user. 

This step closes the window. Because EXIT is both a 
Procedures Language and an OS/2 command, ADDRESS 
CMD is used to pass an EXIT command specifically to 

OS/2 to end the program and close the window. Other¬ 
wise, the window would be left open and would need to 
be closed manually. 


Figure 2. STARTUP.CMD 


Personal Systems/Issue 2, 1990 




71 


SQLCA.SQLCODE 

SQL return code 

SQLCA.SQLERRML 

Length of data in the following variable 

SQLCA.SQLERRMC 

Error message tokens, if an error occured 

SQLCA.SQLERRP 

Eight-byte diagnostics 

SQLCA.SQLERRD. 1 thru 6 

Six-element array of diagnostics 

SQLCA.WARN.O thru 7 

Eight-element array of warning flags 

SQLISL 

Isolation level in use 

SQLMSG 

If the SQLCA.SQLCODE variable is set to a 
value other than zero, this contains text describ¬ 
ing the error 


Figure 5 contains an example of the 
SQLDBS interface. As in OS/2 Ex¬ 
tended Edition Version 1.1, certain 
situations require a START USING 
DATABASE to be performed. 

STOP USING also needs to be pres¬ 
ent in this program, but is not 
shown in this partial example. 

SQL Calls Interface 

The SQLEXEC interface is used to 
process SQL requests. It operates 
on a call/retum basis also. 

The syntax of the API call is as fol¬ 
lows: 

CALL SQLEXEC ’character-string’ 

’Character-string’ can be any one of 
a number of supported SQL calls. 
The character string is delineated by 
quotes and can span multiple lines. 

Figure 6 shows an example of the 
SQLEXEC interface. 


Figure 3. Partial List of SQLCA Variables 

The command string passed to the 
interface is composed of any of the 
following types of elements: 

• SQL keywords 

• Host variables 

• Pre-defined identifiers 


There is support for all SQL key¬ 
words. SELECT, UPDATE, and 
DELETE must be PREPAREd prior 
to execution, because all SQL is ex¬ 
ecuted dynamically with the Proce¬ 
dures Language interface. 

Each host variable is preceded in 
the command string by a colon. 


if SQLCA.SQLCODE \« 0 then signal SQLERR 

The syntax of the call to the Database Manager interface 
will be shown in a following example. The return code 
should be checked immediately following any call to the 
Database Manager. After the call is made, check the re¬ 
turn code stored in SQLCA.SQLCODE. If it is not equal 
to zero, pass control to another part of the program to 
handle the error situation. The SIGNAL command is 
used to pass control to a Procedures Language label 
called SQLERR. 

• 

If the SQLCODE was not set, continue processing in the 
program. 

SQLERR: 

A Procedures Language label is signified by the name 
and the colon character. Control resumes here. This pro¬ 
gram assumes all non-zero SQL codes indicate an error. 

say 'SQL Fatal error:' 

say ' SQLCODE - ' SQLCA.SQLCODE 

say ' SQLMSG = ' SQLMSG 

Display the error code and corresponding message. Note 
that unlike other languages, the Procedures Language 

SQL interface automatically provides an interpreted error 
message for your use. 

exi t 

End of program. 


Figure 4. SQLCODE Checking 
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Three types of host variables are 
used in the SQLEXEC string: 

• Statement 

• Data 

• SQLDA 

Statement host variables are a string 
that contain an SQL statement. As 
an example. Figure 7 illustrates de¬ 
fining a Procedures Language vari¬ 
able to use as a host variable. 

Data host variables are used for 
transferring data to the Database 
Manager or for receiving data from 
an SQL SELECT statement for use 
by the Procedures Language pro¬ 
gram. Figure 8 shows the SQL 
types supported. As stated before. 


Procedures Language regards them 
as typeless. 

SQLDA host variables are used in 
PREPARE, DESCRIBE, OPEN, 
EXECUTE, and FETCH SQL state¬ 
ments. 

A complex (array) variable is used 
to represent the SQLDA. The struc¬ 
ture is shown in Figure 9. 

Further information on the uses of 
the SQLDA can be found in OS/2 
Extended Edition Version 1.2 
Database Manager Programming 
Guide and Reference. 

Predefined Identifiers 

Cursor and statement names are pre¬ 
defined by the interface. Cursor 
names, used in DECLARE, OPEN, 


FETCH, and CLOSE statements, 
range from Cl to Cl00. Statement 
names, used in DECLARE, DE¬ 
SCRIBE, PREPARE, and EXE¬ 
CUTE statements, range from S1 to 
SI00. The interface requires the 
use of these names only. Other lan¬ 
guages allows the program to de¬ 
clare their name. 

Sample Programs 

Now that the Procedures Language 
basics pertaining to the Database 
Manager interface have been dis¬ 
cussed, samples of these basics are 
presented. All the following exam¬ 
ples run in OS/2 windows without a 
presentation interface. 

Procedures Language, like other sup¬ 
ported languages, requires a START 
and STOP USING DATABASE. 


call SQLDBS 

'START USING DATABASE DEMO IN', 
'SHARED MODE' 

Routine calls are very simple to code in Procedures Lan¬ 
guage. Simply enclose the command strings in single 
quotes. Variables outside the quotes can be resolved as 
shown in a later example. 

if SQLCA.SQLCODE \- 0 then signal SQLERR 

Check the SQLCODE after each call. 

SQLERR: 


Code an appropriate error-handling routine as shown in 
the previous example. 


Figure 5. Use of SQLDBS 


call SQLEXEC 'FETCH Cl INTO :acctno racctname' A precompiler is not used by the Procedures Language in¬ 

terface. SQL statements are simply enclosed in parenthe¬ 
ses. The use of host variables is discussed later. 

if SQLCA. SQLCODE \- 0 then signal SQLERR Check the SQLCODE after each call. 


SQL ERR: Code an appropriate error-handling routine. 


Figure 6. Use of SQLEXEC 


Personal Systems/Issue 2, 1990 






73 


creattab - 'create table neworg (', 

The variable CREATTAB will contain the CREATE 
statement. A quote and comma is used to continue defi¬ 
nition of the Procedures Language variable to the next 
line. The variable will be seen as a single string to the in¬ 
terface. 

'deptnum 

smal1int not nul1,', 

The next line starts with a quote and continues the same 

’deptname 

varcharC 14),', 

way as the previous line. 

* 1ocation 

varchar(13) )' 

Following proper SQL syntax, the SQL statement is de¬ 
lineated by a closing parenthesis. 

call SQLEXEC 'EXECUTE 

IMMEDIATE :creattab' 

The statement is executed. SQLCODE should be 
checked for successful completion. 


Figure 7. Statement Host Variable 

Figure 10 shows an example of a 
program that performs this. Be¬ 
cause the code required to perform 
the function is lengthy, the follow¬ 
ing program can be called from any 
Procedures Language program. 

Figure 11 shows an application pro¬ 
gram that displays a table’s contents. 

Figure 12 shows how Procedures 
Language is used to create a 
Database Manager utility. A 
Database Administrator can use Pro¬ 
cedures Language to create many of 
the tools necessary to administer 
Database Manager. This utility 
opens a scan on the volume 
database directory and reports valu¬ 
able information. The program runs 
in an OS/2 window. The Dialog 
Manager could be used by this pro¬ 
gram to create a better presentation 
interface for this utility. 

The preceding examples illustrate 
the simplicity of housing applica¬ 
tion or utility code in Procedures 
Language programs. The next sec¬ 
tion examines how to take advan¬ 
tage of Query Manager 
functionality in Procedures Lan¬ 
guage code. 


Column type 

SQL data type 


not nullable 

nullable 

SMALLINT 

500 

501 

INTEGER 

496 

497 

FLOAT 

480 

481 

DECIMAL 

484 

485 

CHAR 

452 

453 

VARCHAR 

448 

449 

LONG VARCHAR 

456 

457 

GRAPHIC (DBCS) 

468 

469 

VARGRAPHIC (DBCS) 

464 

465 

LONG VARGRAPHIC (DBCS) 

472 

473 

DATE 

384 

385 

TIME 

388 

389 

TIMESTAMP 

392 

393 


Figure 8. SQL Types Supported 


XXX = Any valid variable name 
n = The number of the SQL VAR element 

XXX.SQLN 

Maximum number of variables allowed 

XXX.SQLD 

Current number of valid variables 

XXX. - XXX.n 

SQLVARS, an array occurring 1 to n times, 
which contains the following for each variable 

XXX.n.SQLTYPE 

Data type 

XXX.n.SQLLEN 

Maximum length 

XXX.n.SQLDATA 

Data 

XXX.n.SQLIND 

Name of indicator variable 

XXX.n.SQLNAME 

Name of column 


Figure 9. List of SQLDA Variables 
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Name : 

PL001.cmd 


*/ 

Purpose : 

START or STOP 

USING database 

*/ 

Platform : 

OS/2 Extended 

Edition 1.2 

*/ 




*/ 


arg dbcmd, dbname 


if dbcmd = ’START’ then signal START 
if dbcmd - 'STOP’ then signal STOP 

say ’Error: PL001 invalid command:’ dbcmd 

return 

START: 

call SQLDBS dbcmd, 

’USING DATABASE’ dbname, 

'IN SHARED MODE’ 


if SQLCA.SQLCODE = 0 then signal ENDIT 


if SQLCA.SQLCODE - -1015 then 
do 

call SQLDBS 'RESTART DATABASE’ dbname 
if SQLCA.SQLCODE \- 0 then signal SQLERR 
call SQLDBS dbcmd, 

’USING DATABASE’ dbname, 

'IN SHARED MODE’ 

if SQLCA.SQLCODE = 0 then signal ENDIT 
else signal SQLERR 
end 
el se 

signal SQLERR 

STOP: 

call SQLDBS dbcmd 'USING DATABASE’ 
if SQLCA.SQLCODE \= 0 then signal SQLERR 
ENDIT: 

return 

SQLERR: 

say ’SQL Fatal error:’ 

say ’ SQLCODE - ’ SQLCA.SQLCODE 

say ’ SQLMSG - ' SQLMSG 

say ’PL001:’ dbcmd dbname 'unsuccessful' 

signal ENDIT 


Two arguments are passed from the calling program - a 
START or STOP instruction and the database name 
(used on the START only). 

Branch to the appropriate section depending on the com¬ 
mand received. 

Handle an invalid command. 

The START USING section begins at this label. 

The Procedures Language variables for command and 
database name are embedded in the command. These are 
resolved by Procedures Language before the call is made. 

If the start is successful, go to this label to end the pro¬ 
gram. 

If a restart is required, then RESTART the database. If 
successful, then perform the START USING again. If 
successful, go to this label to end the program. 


If the database still cannot be started, a serious error has 
occurred. Branch to the error-handling session. 

The STOP section. 

Substitute variables as before. 

When complete, return control to the calling program. 

The SQL error-handling code. Display descriptive infor¬ 
mation so the error can be determined. 


Figure 10. START and STOP USING DATABASE 
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/*Name 
/♦PIatform 
/♦Purpose 
/♦Dependency 


PL100.cmd */ 
OS/2 Extended Edition 1.2 */ 
display the SAMPLE ORG table ♦/ 
SAMPLE database installed */ 


call PL001 START. SAMPLE 


The program must first execute a START USING 
DATABASE. The program shown in the previous exam¬ 
ple will be used to START USING DATABASE SAM¬ 
PLE. This program uses the optional sample database 
delivered with OS/2 Extended Edition 1.2, which was in¬ 
stalled using the SQLSAMPL command. 


stmtbuf = 'select * from org order by deptnumb' 


A statement host variable is used to house the SQL SE¬ 
LECT statement. 


call SQLEXEC 'PREPARE si FROM :stmtbuf' 
if SQLCA.SQLCODE \= 0 then signal SQLERR 


The statement is prepared for execution. Error checking 
is performed. 


call SQLEXEC 'DECLARE cl CURSOR FOR si’ 
if SQLCA.SQLCODE \= 0 then signal SQLERR 
call SQLEXEC 'OPEN cl' 

if SQLCA.SQLCODE \= 0 then signal SQLERR 


do while SQLCA.SQLCODE - 0 
call SQLEXEC 'FETCH cl INTO 

:deptnumb 
:deptname 
:manager, 
:divisi on 
: 1 ocation 

if SQLCA.SQLCODE - 0 then 
do 



say 

*★★★★*★★★★★★★★★★★★★★★★★★★★★★★* 

say 

'Department 

Number 

-' deptnumb 

say 

'Department 

Name 

-' deptname 

say 

'Manager 


=’ manager 

say 

’ Divisi on 


=' division 

say 

’ Locati on 


-' location 


end 


A cursor is declared for the SELECT statement. 

The cursor is opened. 

A DO loop will be performed repetitively while the 
SQLCODE is equal to zero. Any non-zero SQLCODE 
will cause control to drop out of the loop. The DO loop 
is delineated by an END statement. A FETCH statement 
selects the first or next row. 

If the SQLCODE from the fetch is zero, then the row can 
be displayed. An IF-THEN statement conditionally exe¬ 
cutes statements 8, 9 and 10. Similar structured program¬ 
ming statements in other languages are known as Case 
Statements. 

Each column of the row is displayed. 


The delineator of the conditional IF-THEN statement. 


end 


The delineator of the DO loop. 


if SQLCA.SQLCODE \= 100 then signal SQLERR 


signal ENDIT 


SQLERR: 

say 'SQL Error:' 

say ' SQLCODE - ' SQLCA.SQLCODE 

say ’ SQLMSG = ' SQLMSG 

ENDIT: 

call SQLEXEC 'CLOSE cl' 

call PL001 STOP 

exit 


A check to see if the DO loop ended from an abnormal 
SQL condition code. If so, pass control to the SIGNAL 
label to handle the error. 

If an error did not occur, pass control to the ENDIT label 
to terminate the program. 

The SQL error-handling code. Pertinent variables will be 
displayed to assist in problem resolution. 

The ENDIT label. The open cursor is closed, and a call 
is made to the subroutine to STOP USING the database. 
An exit statement ends the program and returns control 
to OS/2. 


Figure 11. An Application Program 
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/* 

Name 

: PL008.cmd 

*/ 

/* 

Purpose 

: Database Directory Scan 

*/ 

/* 

PIatform 

: OS/2 Extended Edition 1.2 

*/ 

/* 



*/ 


call SQLDBS 'OPEN DATABASE DIRECTORY ON C\ 

* USING :scanvar' 

if SQLCA.SQLCODE \- 0 then signal SQLERR 
say 

say '-’' 

say * Database Directory Scan for C Drive* 
do i-1 to scanvar.2 


call SQLDBS 'GET DATABASE DIRECTORY ENTRY', 
'rscanvar.l USING rentry' 
if SQLCA.SQLCODE \- 0 then signal SQLERR 


say say 'Database:' entry.2 'Alias:' entry. 

'Drive:' entry.3 

say ' Internal name :' entry.4 

say ' Node name :' entry.5 

say ' Dbtype :' entry.6 

say ' Comment :' entry.7 

say ' Codepage :' entry.8 

say ' Enttype :' entry.9 

say 
say 
pause 
end 

say '-' 

say 

call SQLDBS 'CLOSE DATABASE DIRECTORY', 

':scanvar.1' 

if SQLCA.SQLCODE \- 0 then signal SQLERR 


This statement opens a directory scan for drive C. All 
databases located on drive C will be reported. The first 
element in the compound variable “scanvar” will contain 
a value for the scanid. 


The second element of the compound variable scanvar 
contains the number of databases on the drive. The loop 
will be performed this many times. The variable “i” will 
be used as a counter for a loop. 

The first element of the compound variable scanvar con¬ 
tains a unique identifier for the scan. This variable identi 
ties to Database Manager the resources allocated to the 
scan. 


A compound variable was returned containing the infor¬ 
mation about the database. Each element of this variable 
is displayed. 


A pause command is used to give users time to read the 
information. Dialog Manager could be used to handle 
user interaction more eloquently. 

The scan is closed using the unique identifier. Appropri¬ 
ate error-code checking is performed. 


ENDIT: 

ADDRESS CMD 'EXIT' 


SQLERR: 

say 'SQL Fatal error:' 

say ' SQLCODE - ' SQLCA.SQLCODE 

say ' SQLMSG * ' SQLMSG 

call SQLDBS 'CLOSE DATABASE DIRECTORY :scanvar' 
pause 

signal ENDIT 


Figure 12. Database Directory Scan 
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Query Manager Callable 
Interface 

The Query Manager Callable Inter¬ 
face (QMCI) contains an interface 
for: (1) starting the Query Manager 
interface, (2) passing commands to 
the Query Manager and acting upon 
the results of those commands, and 
(3) stopping the Query Manager in¬ 
terface. 

Like the Database Manager inter¬ 
face, the QMCI works on a call/re- 
tum basis and uses a 
communications area to pass infor¬ 
mation. The QMCI handles the in¬ 
terface to the Database Manager 
beneath the surface. The QMCI 
handles the interface to the 
Database Manager. Therefore, 
START and START USING state¬ 
ments should not be coded unless 
the program is also performing SQL 
calls in addition to the QMCI calls. 

The QMCI follows the Systems Ap¬ 
plication Architecture™ (SAA™) 
Query CPI format. This format is 
consistent with the functionality of 
Query Management Facility™ Ver¬ 
sion 2.4 on MVS and VM systems. 

The QMCI allows a program to 
take advantage of all Query Man¬ 
ager facilities and resources. Using 
the QMCI can save having to code 
equivalent functions separately. Sig¬ 
nificant development effort can be 
saved. Furthermore, if end users 
are already familiar with the Query 
Manager, using a familiar interface 
will save documentation and train¬ 
ing time. 

Four types of statements are neces¬ 
sary for a program to use the Query 
Manager Callable Interface: 

• A communications area 
(DSQCOMM) 


• START the interface 

• QM session commands 

• EXIT the interface 

The variables used in the communi¬ 
cations area are all predefined by 
the QMCI interface. These vari¬ 
ables will be used both as return 
codes and as working storage areas. 

Four DSQCOMM variables contain 
completion information: 

DSQ_RETURN_CODE indicates 
the call’s outcome. Values returned 
are: 

• 0 : successful execution 

• 4 : successful execution with a 
warning 

• 8 : command did not execute cor¬ 
rectly 

• 16: severe error, the QMCI ses¬ 
sion is terminated. 

DSQ_REASON_CODE contains a 
further explanation of the call’s out¬ 
come. 

DSQ_ERROR_ID and DSQ_MES- 
SAGE_ID contains error informa¬ 
tion. 

The interface is initiated with the 
START command. A partial list of 
the optional parameters are: 

1. DSQSMODE defines how the in¬ 
terface will be used. The QMCI 
can be run in BATCH or INTERAC¬ 
TIVE mode. Interactive means that 
Query Manager screens will be dis¬ 
played for the user. Batch mode in¬ 
dicates that screens will not and 
cannot be displayed. 

As an example of BATCH versus 


INTERACTIVE, consider an appli¬ 
cation requirement that produces a 
customer report. If input from the 
user is not necessary to run the re¬ 
port, then BATCH would be used. 
The application does not display 
any Query Manager panels as it 
runs. 

If input is required (perhaps the re¬ 
port is run for a certain customer), 
then INTERACTIVE would be 
used. When run, a Query Manager 
panel would be displayed asking for 
a customer number that would set a 
Query Manager variable. That vari¬ 
able would then be used exactly as 
in a stand-alone Query Manager pro¬ 
cedure. 

2. With DSQSPROF, a Query Man¬ 
ager profile may be specified. A 
profile can indicate which database 
to use for subsequent queries, or 
can indicate a Query Manager proce¬ 
dure to be run at initiation of the 
session. 

3. DSQSDBNM can be used to 
specify which database to use. 

4. DSQSRUN specifies a Query 
Manager procedure to run. Note 
that the procedural language used 
by Query Manager is a limited sub¬ 
set of Procedures Language. See 
the OS/2 Extended Edition Version 

1.2 Users Guide for a complete de¬ 
scription of the Query Manager pro¬ 
cedural command syntax. 

5. DSQSCMD is the name of an op¬ 
tional .CMD file to execute. This 
command file will be used to start 
Query Manager and optionally pass 
parms to it. If DSQSCMD is not 
specified, 

\SQLL1B\QRWEXECZ.CMD is 
used. This batch command, which 
is delivered with OS/2, is used to 
start Query Manager in a stand¬ 
alone mode. If your application pro- 
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/* 

Name 

QM001.cmd 

* 

/* 

Purpose 

Sample QM Cl - Interactive 

*/ 

/* 

PIatform 

OS/2 Extended Edition 1.2 

*/ 

/* 

Dependency 

QM query ’select * from 

*/ 

/* 


staff’ 

*/ 

/* 



*/ 


say 'QM001 - QM Cl Interactive* 
say 

say 'Start database SAMPLE’ 

CALL DSQCIX , 

’START*,* DSQSMODE=INTERACTIVE* , 

* DSQSDBNM="SAMPLE"* 

if DSQ_RETURN_CODE \= 0 then signal QMERR 
say ’Edit table’ 

CALL DSQCIX ’EDIT TABLE STAFF’ 
if DSQ_RETURN_CODE \= 0 then signal QMERR 

say ’Run query’ 


Because this program is run in an OS/2 window, a mes¬ 
sage is displayed to the user. 

The QMCI is started in interactive mode for the database 
SAMPLE. The user has not yet seen a Query Manager 
screen. Because the database to be used is specified, the 
usual first Query Manager screen that shows the list of 
databases will not be shown. 

The user is now in edit mode for the specified table. At 
this point, the first Query Manager screen is displayed. 
This is the familiar edit screen to choose Add or Change. 
After the choice is made, the user is in Edit mode. 


CALL DSQCIX ’RUN QUERY ALL_OF_STAFF’ 


if DSQ_RETURN_CODE 

\- 0 

then 

signal 

QMERR 

say 'Print report’ 





CALL DSQCIX 'PRINT 
if DSQ_RETURN_CODE 

REPORT’ 

\= 0 then 

signal 

QMERR 

say ’Exit’ 

CALL DSQCIX 'EXIT' 
if DSQ_RETURN_.CODE 

\= 0 

then 

signal 

QMERR 


After the edit is complete, this query is run, and the 
Query Manager report screen is displayed. This is the 
last Query Manager screen the user will see. 

After the report is viewed, it is routed directly to the 
print queue. Print options can also be specified if desired. 

The interface is stopped. 


ENDIT: 

ADDRESS CMD ’EXIT’ 


The program is ended, and the window is closed. 


QMERR: 

say ’The QM Cl has ended with a non-zero’, 
'Return Code:’ 


say 

say 

say 

say 

say 

say 


DSQ_RETURN__CODE 
DSQ_REAS0N_C0DE 
DSQ_ERROR_ID 
DSQ MESSAGEID 


DSQ_RETURN_CODE 
DSQ.REASON.CODE 
DSQ_ERROR_ID 
DSQ_MESSAGE_ID 


pause 

signal ENDIT 


In case of error, pertinent variables are displayed. 


Figure 13. Interactive QMCI Application 


gram needs to change this proce¬ 
dure, make a copy of it using a new 
name. 

Figure 13 is an example of an inter¬ 
active execution using QMCI. In 
this example, the user will edit the 


table STAFF. When complete, a 
query is run showing the entire 
STAFF table. After the user has re¬ 
viewed the query results, the query 
is printed directly to the print queue 
and the interface is ended. 


Figure 14 shows a batch QMCI pro¬ 
gram. This program displays mes¬ 
sages in the OS/2 window as it 
runs, but does not display any 
Query Manager screens. 


Personal Systems/Issue 2, 1990 





79 


/* 

Name 

: QM002.cmd 

*/ 

/* 

Purpose 

: Sample QM Cl - Batch 

*/ 

/* 

PIatform 

: OS/2 Extended Edition 1.2 

*/ 

/* 

Dependency 

: QM query 'Select * from 

*/ 

/* 


staff’ 

*/ 

/* 



*/ 


say 

say *QM002 - QM Cl Batch* 
say 

say 'Start in batch mode with database SAMPLE' 
CALL DSQCIX, 

'START',' DSQSMODE=BATCH',' DSQSDBNM="SAMPLE" ' 


if DSQ_RETURN_CODE 

\= 0 

then 

signal 

QMERR 

say 'Run query' 

CALL DSQCIX 'RUN QUERY 

ALL_0F 

.STAFF’ 

r 

'(INTERACTING)' 
if DSQ RETURN CODE \= 0 

then 

signal 

QMERR 

say 'Print report’ 

CALL DSQCIX 'PRINT 
if DSQ_RETURN_CODE 

REPORT’ 

\= 0 then 

signal 

QMERR 

say 'Exit' 

CALL DSQCIX 'EXIT' 
if DSQ_RETURN. CODE 

\- 0 

then 

signal 

QMERR 


ENDIT: 

ADDRESS CMD 'EXIT' 


QMERR: 

say 'The QM Cl has ended 

with a non-zero’, 

say 
say ' 

’Return Code: ' 

DSQ_RETURN_CODE 

' DSQ__RETURN CODE 

say ’ 

DSQ REASON CODE 

’ DSQ REASON CODE 

say ' 

DSQ ERROR ID 

' DSQ ERROR ID 

say ' 

DSQ_MESSAGE_ID 

' DSQ_MESSAGE_ID 

say 
pause 
signal 

ENDIT 



The interface is started in batch mode. 


A query is run that produces a report. The INTERACT 
parm is set to NO to tell Query Manager not to show a 
screen. Without this parm, the QMCI will fail by at¬ 
tempting to display a screen while in batch mode. 

The report is sent to the print queue. No Query Manager 
screens have been shown. 


Figure 14. Batch QMCI Application 


Conclusion 

This article has introduced the inter¬ 
faces to Procedures Language 
2/REXX shown with examples of 
how powerful they can be for both 
tool and application development. 
Further examples and complete dis¬ 
cussion of the syntax involved is 
available in the OS/2 Extended Edi¬ 
tion Version 1.2 manuals. 
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Three main areas for performance 
improvement are considered in 
this article: (1) configuring APPC 
and the Data Link Control compo¬ 
nents (DLCs) in the OS/2 Commu¬ 
nications Manager; (2) designing 
and writing APPC transaction pro¬ 
grams; and (3) providing a 
hospitable OS/2 environment 
when running programs. 

Advanced Program-to-Program 
Communications (APPC) software 
is an integral part of the OS/2 Ex¬ 
tended Edition (EE) Communica¬ 
tions Manager. It implements the 
System Network Architecture 
(SNA) Logical Unit (LU) type 6.2. 
This provides an application pro¬ 
gramming interface to OS/2 pro¬ 
grams, which allows them to 
exchange information with similar 
programs located anywhere in an 
SNA network. 

This article suggests steps that can 
be taken to make APPC applica¬ 
tions run as fast as possible in OS/2. 
It makes no claims to consider the 
performance of other concurrent 
OS/2 processes or the hardware of 
the machines. It also makes no 
claims as to the performance gains 
to be expected by making any of 
these changes. Actual performance 
gains will be dependent on the par¬ 
ticular configuration. The steps 
listed here apply to OS/2 EE Ver¬ 
sion 1.2 and earlier; they may not 


necessarily apply to any future ver¬ 
sion of APPC in OS/2 EE. 

As is often the case, there are many 
trade-offs that must be taken into 
consideration - program size, mem¬ 
ory costs, usability, and simplicity - 
to gain performance. Those aspects 
should be considered when making 
any of the changes suggested here. 


Some Background APPC 
Information 

The Communications Manager por¬ 
tion of IBM’s OS/2 EE contains a 
variety of software components to 
handle computer communications. 
One of these components is Ad¬ 
vanced Program-to-Program Com¬ 
munications. APPC is an 
implementation of LU-type 6.2, 
which is one of the primary parts of 
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IBM’s Systems Network Architec¬ 
ture (SNA). The IBM Systems Net¬ 
work Architecture Technical 
Overview (GC30-3073) provides a 
technical overview of SNA. 

Programmers would normally write 
a pair of communications programs 
in such a way that when a local pro¬ 
gram starts a remote program, they 
would begin exchanging informa¬ 
tion - that is, they would enter into 
a conversation. These programs 
can request a number of services 
from APPC; to use these services 
they issue verbs. APPC verbs have 
names such as ALLOCATE (to set 
up a conversation), SEND_DATA 
(to send data to a remote program), 
and RECEIVE AND WAIT (to 
wait for data to arrive from a re¬ 
mote program). When APPC fin¬ 
ishes its work on a verb, it sets a 
return-code field and returns to the 
calling program. If the verb has ex¬ 
ecuted successfully, the return code 
indicates “OK.” Otherwise, the re¬ 
turn code shows why APPC was un¬ 
able to satisfy the verb request. 

A logical unit is a piece of internal 
APPC software that accepts and pro¬ 
cesses verbs. It acts on behalf of a 
program that is issuing verbs to it. 

To exchange data between a pair of 
machines, a local LU maintains one 
or more sessions with a remote LU. 
Each conversation uses one session, 
which serves to transport the data 
between two logical units. Gener¬ 
ally, the local and remote LUs are 
located in two different machines, 
but with a multitasking operating 
system such as OS/2, both LUs may 
be physically located in the same 
machine. 

The term transaction program (TP) 
has a special meaning in APPC, and 
it is quite different from a “pro¬ 
gram” as we know it in OS/2. A 
TP is not an OS/2 program; it is a 


section of an OS/2 program. Unfor¬ 
tunately, these names are a little 
confusing! 

Figure 1 shows an OS/2 program 
with multiple TPs using the APPC 
and common services components 
of the OS/2 Communications Man¬ 
ager. 

Starting a TP is simply a matter of 
issuing one of two verbs. When an 
OS/2 program successfully issues a 
TP STARTED or RECEIVE AL- 
LOCATE verb, it identifies itself 
as a new entity (a TP) that APPC 


needs to know about. APPC inter¬ 
nally sets aside a group of memory 
blocks for the TP, and devises a 
unique TP identifier (a tp_id), 
which it returns to the calling pro¬ 
gram. 

An OS/2 program must supply that 
tp id on all conversation verbs it is¬ 
sues while part of that TP. Many 
tp ids may be active at any time in 
an OS/2 process, but a tp_id cannot 
be shared with other processes. If 
an OS/2 program issues a 
TP ENDED verb, APPC internally 
clears its buffers for that TP and 


Local Machine 



Figure 1. An OS/2 Program with Multiple Transition Programs (TPs) 
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marks the tp_id as invalid. If an 
OS/2 program terminates, APPC 
ends all the active TPs associated 
with that process. 

Conversations similarly have their 
own identifiers (known as 
conv_ids), and a TP must be estab¬ 
lished before a conversation can be 
allocated. Many conversations may 
use a single tp_id concurrently 
(such as in multiple threads) or se¬ 
quentially (where one conversation 
follows another). When a TP ends, 
APPC deallocates all of its active 


Figure 2. A Sample SNA Network Connection 


conversations. Figure 2 shows 
three nodes connected through an 
SNA network. 

There are two types of conversa¬ 
tions: basic and mapped. Basic con¬ 
versation verbs require the program 
to put a two-byte length field at the 
beginning of each data block. 

Some of the basic conversation 
verbs have extra parameters that the 
mapped verbs do not, allowing 
some additional flexibility. By con¬ 
trast, a mapped conversation pro¬ 
vides the features required for 


information exchange in an easy-to- 
use, record-level manner. 

In previous paragraphs, we spoke of 
APPC verbs named ALLOCATE, 
SEND_DATA, and so on. These 
are actually basic conversation 
verbs; their mapped conversation 
counterparts are named MCALLO- 
CATE and MC_SEND DATA. In 
the remainder of this paper, when¬ 
ever either a basic or mapped form 
of a verb is allowed, it is signified 
by surrounding the “MC_” with 
square brackets; for example, 

[MC JSEND DATA signifies both 
SEND DATA and 
MC_SEND DATA. 

There is more information on APPC 
concepts and operation in the IBM 
Systems Network Architecture Trans¬ 
action Programmer s Reference 
Manual for LU Type 6.2 (GC30- 
3084). The IBM Operating Sys¬ 
tem/2 Extended Edition APPC 
Programming Reference (S90X- 
7910) specifically describes how to 
use APPC with OS/2 EE. 

Configuring the 
Communications Manager 

A series of menus and panels are 
used to set up the data link control 
(DLC), LUs, sessions, and TPs in 
OS/2. Performing this setup is 
known as “configuring APPC”; 
when configuring setup is complete, 
the values entered are verified to 
see that they properly cross- 
reference each other. APPC’s use 
of memory and DLCs is tailored 
through configuration. 

Complete details on configuring the 
OS/2 EE Communications Manager 
are found in the IBM Operating Sys¬ 
tem/2 Extended Edition System 
Administrator s Guide (S90X- 
7908). The following steps can im¬ 
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prove APPC throughput without 

needing to change programs. 

Step 1: Provide appropriate trans¬ 
mit and receive buffer sizes for the 

DLC. 

a. Use as much as possible of the 
data buffering capability of the 
LAN adapter when configuring 
the “LAN Feature Profile.” 

Using large transmit buffers al¬ 
lows large Request/Response 
Unit (RU) sizes to be configured 
for APPC. Large RUs dramati¬ 
cally increase throughput; we 
have seen performance improve 
by a factor of nine in our labs. 
The trade-off in using large trans¬ 
mit buffers is that more adapter 
and system memory is con¬ 
sumed, and some degradation in 
short transactions may be experi¬ 
enced. The buffer sizes are read 
from the configuration file when 
OS/2 is booted, since the config¬ 
uration file is named in CON¬ 
FIG.SYS. Thus, these buffer 
sizes are used by all the commu¬ 
nications software using that 
LAN adapter, not just APPC. 

For example, set the maximum 
RU size to 1,500 bytes if using 
an Ethernet Adapter, 1,920 bytes 
if using an IBM Token-Ring 
Adapter or Token Ring 
Adapter/A, or as high as 15,360 
bytes if using Token Ring 16/4 
adapters. The Transmit Buffer 
Size should be set to the maxi¬ 
mum RU size + 24. The Re¬ 
ceive Buffer Size should be set 
to the minimum RU size (set in 
the Mode profile) + 24. 

Why is 1920 the optimal RU 
size for 4Mbps token-ring adapt¬ 
ers with 2 KB buffers? The size 
of the RU negotiated during ses¬ 
sion setup is of the form 


a x 2 b 

where a and b are positive inte¬ 
gers, and a is between 8 and 15. 
Note that 

1920= 15 x 2 7 

Because 24 additional bytes are 
needed for frame overhead, 

1920 + 24 = 1944 <= 2048 
(which is 8 x 2 8 ) 

1920 is the largest number of the 
proper form less than 2048, 
which is the hardware buffer 
size. With a different hardware 
buffer size on the adapter, this 
formula can be used to calculate 
what the largest RU size can be. 

Although the IBM Token-Ring 
16/4 Adapter can support a 
Transmit Buffer Size of 16 KB, 
configuring the largest Transmit 
Buffer Size may result in 
slightly poorer performance than 
using a value around 15 KB; hav¬ 
ing two 16 KB transmit buffers 
leaves less than 32 KB for the re¬ 
ceive buffers. If the available re¬ 
ceive buffer space is inadequate 
to handle an incoming frame, the 
frame is rejected and must be re¬ 
transmitted. 

b. The minimum number of receive 
buffers must be between 2 and 
151. For best performance, use 
the result of the following equa¬ 
tion: 

# Receive _ ('Transmit Buffer Size x 2) 
B uffers Receive B uffer Size 

Because the improvement can be 
so dramatic, you should experi¬ 
ment with different sizes of trans¬ 
mit and receive buffers for the 
particular environment. One 
user who reported a significant 


improvement by using large 
transmit and receive buffers tried 
the following test with his server 
machine. After configuring the 
receive buffers as previously de¬ 
scribed, he then configured twice 
as many receive buffers, each 
half the previous size. He re¬ 
ported a performance improve¬ 
ment of another 30 percent. 

c. The maximum number of link 
stations for the LAN adapter 
should be minimized, because 
this serves to multiply the 
adapter memory needed for trans¬ 
mit and receive buffers. For 
each adapter, coordinate the 
Maximum Number of Link Sta¬ 
tions configuration among three 
places: the “Data Link Control 
(DLC) profile,” and the IEEE 
802.2 and NETBIOS profiles in 
the “LAN Feature profile.” If 
NETBIOS is not being used, set 
its Maximum Number of Link 
Stations to 0 to simplify the cal¬ 
culation. 

d. SDLC and X.25 links sometimes 
encounter a relatively high level 
of line noise, so the optimal 
buffer size depends on the error 
rate of the link. If the error rate 
is high, using large frames will 
slow performance, because they 
may frequently need to be re¬ 
transmitted. An extended discus¬ 
sion of the trade-offs between 
buffer size and bit error rate for 
SDLC can be found in the arti¬ 
cles by K.C. Traynham and R.F. 
Steen, “Interpreting SDLC 
Throughput Efficiency, Part 1 - 

3 Models and Part 2 - Results,” 
Data Communications , October 
and November 1977, pages 43- 
51 and 59-66. 

Step 2: Match the Maximum RU 

size on the Mode to the Maximum 

RU size on the DLC. 
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To minimize the number of line 
flows, make these sizes equal to 
each other, and as large as possible. 
The mode’s RU size determines the 
size of a data block exchanged on a 
session; the DLC’s RU size deter¬ 
mines the size of a data block ex¬ 
changed on a link. Many sessions 
may concurrently use one link. The 
Communications Manager Verify 
will not allow the Maximum RU 
size on the “Transmission Service 
Mode profile” to exceed the Maxi¬ 
mum RU size on the “Data Link 
Control (DLC) profile.” 

Step 3: Use the default DLC win¬ 
dow sizes. 

For best performance, the Data Link 
Control should send and receive as 
much data as possible before requir¬ 
ing an acknowledgment. DLC pac¬ 
ing takes place on each link 
between a pair of DLC adapters. It 
specifies the number of frames that 
the local DLC can send and receive 
before requiring an acknowledg¬ 
ment from the remote DLC. 

Intuitively, one would think that the 
Send window count and Receive win¬ 
dow count fields should be set to 
their largest configurable values. 
However, the equation is much 
more complex - especially for 
LANs - involving the topology, traf¬ 
fic, frame size, load on the remote 
machine, and these two window 
counts. For the token-ring LAN, it 
also involves the value for the T1 
Acknowledgment Timer. So, al¬ 
though they may seem a little 
counter-intuitive, the default values 
in the DLC configuration have been 
demonstrated in our labs to give the 
best performance, considering all of 
these factors. We recommend ex¬ 
perimenting with this value among 
the computers in individual environ¬ 
ments. 


Note: Depending on the capabili¬ 
ties of the remote machine, the win¬ 
dow counts may need to be 
configured to match exactly those 
configured at the remote machine. 

Step 4: Use moderately sized pac¬ 
ing windows for the sessions. 

Session pacing is used to tell the re¬ 
mote LU how many RUs it can 
send before the local buffers might 
be overrun. For example, if the re¬ 
ceive pacing window is “8,” the re¬ 
mote LU will stop sending after the 
eighth RU - until the local LU 
gives permission to again begin 
sending. Best performance for a 
session occurs when APPC can 
send and receive as much data as 
possible before requiring a message 
exchange with the remote LU. 

Ideally, one would configure for no 
pacing, that is, set the Receive Pac¬ 
ing Limit field in the “Transmission 
Service Mode profile” to zero (0). 
However, APPC can abend if too 
much “unpaced” data arrives and its 
memory allocation is exceeded. 
Using no pacing can also be harm¬ 
ful to the SNA network by overrun¬ 
ning the buffers of machines doing 
intermediate routing. 

Instead, set the Receive Pacing 
Limit field for the mode to its de¬ 
fault value, which is “8.” Although 
it can be set to anything up to 63, 
the performance gain above about 
eight appears to be negligible, and 
the additional buffers that APPC 
would need are allocated from the 
available OS/2 memory. This value 
will be negotiated with the remote 
LU when the session is established, 
so coordinate the session pacing 
window values in both machines. 

However, if many sessions are ac¬ 
tive with large pacing windows, 
OS/2 may begin swapping to disk. 


because of lack of memory. These 
concerns will need to be balanced 
in the environment in which the ses¬ 
sion is running. 

Step 5: Avoid session contention, 
when configuring parallel sessions. 

Determine the number of contention 
winners and losers for each side, 
and configure these appropriately 
on each side. Contention winners 
and losers are important when paral¬ 
lel sessions are configured between 
a pair of LUs. For best perfor¬ 
mance, the machine issuing an 
[MCJALLOCATE verb should al¬ 
ways get a contention winner ses¬ 
sion. 

For example, a Partner LU session 
limit might be configured as 10. 

This means 10 sessions may exist in 
parallel between two LUs. The con¬ 
tention winners and losers values de¬ 
termine which LU owns each of 
these 10 sessions. If the local LU 
has been configured with its Mini¬ 
mum number of contention winners 
source (that is, its contention win¬ 
ners) as five and its Minimum num¬ 
ber of contention winners target 
(that is, its contention losers) as 
two, then three sessions are “up for 
grabs.” If it is known which LU 
should own each of the sessions, 
configure the two LUs to agree. In 
this example, the 10 sessions might 
be divided among the two LUs, as 
follows: 

Local LU Remo te LU 

winners: 6 winners: 4 

losers: 4 losers: 6 

Step 6: Auto-activate sessions, 
when possible. 

Rather than waiting to bring up ses¬ 
sions when an [MC_]ALLOCATE 
verb is issued (which may delay the 
sending of data), bring up all the an- 
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ticipated sessions when APPC is 
started. To do this, specify a non¬ 
zero value for the Number of auto¬ 
matically activated sessions field 
(part of the “Initial Session Limit 
profile”). The value specified there 
should be less than or equal to the 
value configured for the contention 
winners. 

In OS/2 EE Version 1.2, sessions 
can also be auto-activated using the 
CNOS management verb. The 
CNOS verb should be used spar¬ 
ingly: try issuing it once, to bring 
up the sessions for a given LU, part¬ 
ner LU, and mode when they are 
needed. 

Step 7: Specify unique Node ID 
values on each machine. 

Additionally, when using SDLC, 
configure one DLC as primary and 
its partner as secondary. When 
APPC activates a link, a pair of 
XID exchanges will be saved if the 
node IDs are unique and the link sta¬ 
tion roles are already established as 
primary and secondary. Carefully 
coordinate this configuration among 
all machines involved, because er¬ 
rors here can waste lots of time in 
troubleshooting. The Node ID is 
configured in the “SNA Base pro¬ 
file.” 

APPC attempts to activate a link in 
the following situations: 

• when APPC is started, 

• when a session is being estab¬ 
lished and the link it needs is not 
active, 

• when the Subsystem Manage¬ 
ment panels are used to activate a 
link, or 

• when the remote machine initi¬ 
ates the link activation. The part¬ 


ner is probably in one of the pre¬ 
ceding three situations. 

Step 8: Configure Free Unused 
Links as No when using a small 
number of links frequently. 

The Free Unused Links field in the 
“Data Link Control (DLC) profile” 
specifies whether a link is automati¬ 
cally deactivated when no sessions 
are using it. If the TPs frequently 
bring up and take down sessions 
with a few partners, best perfor¬ 
mance can be obtained by leaving 
the link up when there are no ses¬ 
sions. The next time a session is 
started, the link is already active 
and is waiting to be used. This can 
be beneficial in a LAN environ¬ 
ment, where the overhead to main¬ 
tain a link is low. 

If sessions are established with a 
great number of different partners, 
APPC must maintain many sets of 
control blocks for the different links 
- possibly degrading performance. 
Consider configuring Free Unused 
Links as Yes in this case, as well as 
when configuring switched SDLC 
profiles. 

Step 9: Minimize the number of 
LUs, partner LUs and modes config¬ 
ured. 

Many transaction programs (TPs) 
may use the same LU. This can be 
made particularly easy by writing 
the TPs to use the default LU (that 
is, specify the LU_alias as all zeros 
on the TP_STARTED verb). One 
partner LU configuration is needed 
for each remote machine, but the 
need for multiple partner LUs per re¬ 
mote machine can usually be mini¬ 
mized. Coordinate the mode names 
used with each remote machine to 
minimize the total number of modes 
required. 


Designing and Writing TPs 

The primary suggestion in this sec¬ 
tion is to minimize the number of 
calls to APPC or ACSSVC (for 
common services verbs). It is rec¬ 
ommended that a transaction pro¬ 
gram be designed in such a way 
that it causes the least amount of 
code execution in APPC as possible. 

Each time APPC or ACSSVC is 
called, the verb control block and 
(if present) the data buffer are 
checked to see that they are the 
proper length, have the proper seg¬ 
ment attributes, and so on. When 
possible, combine functions in a sin¬ 
gle verb, and send and receive large 
blocks of data. Some specific ways 
to do this are described in the fol¬ 
lowing suggestions. 

1: Minimize changing conversation 
states between Send and Receive. 

The underlying nature of LU6.2 is 
inherently “half-duplex;” that is, 
only one side of a conversation 
sends at a time. Here are a couple 
of ways to minimize the number of 
state changes: 

a. Send as much data as possible 
before receiving or requesting a 
confirmation. 

b. Programs can be designed to use 
two simultaneous conversations, 
one sending and one receiving, 
each on its own session. Figure 
3 shows one user’s design, 
where each thread contains a TP 
that is dedicated to either send¬ 
ing or receiving data. 

Be careful that your programs do 
not become too complex in your ef¬ 
forts to avoid a state change. 

2: Use “combined-receive” indica¬ 
tors for the RECEIVE verbs. 


Personal Systems/Issue 2, 1990 


86 


In OS/2 EE Version 1.2, APPC can 
return both data and status to a TP 
using a single RECEIVE verb. (In 
earlier versions, two RECEIVE 
verbs were required: one for the 
data and one for the status.) Use 
this capability freely on all RE¬ 
CEIVE verbs. 

3: Use the type parameter on 
[MC_]SEND_DATA to combine 
operations. 

In OS/2 EE Version 1.2, a TP can 
combine other verb operations with 
each [MC_]SEND_DATA, such as 
FLUSH, CONFIRM, and 
DEALLOCATE. This can often 
save an extra call to APPC. 

4: Minimize use of the 
[MCJCONFIRM verb and 
syncJevel(CONFIRM). 


[MCJCONFIRM forces a transac¬ 
tion program to wait for an explicit 
acknowledgment from the partner. 
Don’t use the confirm functions un¬ 
less positive acknowledgment is re¬ 
ally required. Instead of asking for 
confirmation after each Send, the 
paired TPs should be written to 
issue an [MCJSEND ERROR 
only when they detect some failure 
in the data being transmitted. 

5: Minimize use of the 
[MCJSENDERROR verb. 

[MCJSENDERROR is used to 
notify the transaction program at the 
remote location that an error has 
been detected. 

[MCJSEND ERROR should not 
be part of the mainline Send-Re- 
ceive path of the TPs. It should 
probably only be used when either 
partner detects a real error situation. 


Station A 

Station B 

Thread 1: * 

Thread 1: 

TP_STARTED (ret: tp_id) 

RECEIVE_ALLOCATE 

ALLOCATE (ret: conv_id) 

(ret: tp id & conv id) 

Do forever: 

Do forever: 

| Wait for data to send 

| RECEIVE_AND_WAIT 

| SEND_DATA 

| Enqueue rcvd data 

| FLUSH 

to user 

DEALLOCATE (at end of day) 


TP_ENDED 

TP_ENDED (after dealloc¬ 


ate rcvd) 

Thread 2: *- 

Thread 2: 

RECEIVE_ALLOCATE 

TP_STARTED (ret:tp_id) 

(ret:tp id & conv id) 

ALLOCATE (ret:conv_id) 

Do forever: 

Do forever: 

| RE C EIVE_AND_WAIT 

| Wait for data to send 

i Enqueue rcvd data to user 

| SEND_DATA 


| FLUSH 


DEALLOCATE (at end of 


day) 

TP_ENDED (after deallocate 

TP_ENDED 

rcvd) 



Figure 3. Two Workstations Using Two Simultaneous Conversations 


In addition to causing two internal 
message exchanges with the partner, 
issuing an [MC JSENDERROR 
verb causes APPC to write an entry 
to the Communications Manager 
error log. 

6: Minimize use of the [MCJRE- 
QUEST TO SEND and 
[MCJPREPARE TO RECEIVE 

verbs. 

When possible, the local and remote 
TPs should be written so that they 
are aware of the current state of the 
conversation, and change their Send 
and Receive states when appropri¬ 
ate. The state of the conversation is 
known at all times, based on which 
verb was issued and the return 
codes and what_received indicators 
that are returned. The APPC Pro¬ 
gramming Reference describes these 
states for each verb, indicator, and 
return code. 

7: Minimize use of the [MCJRE- 
CEIVE AND POST verb. 

Every [MCJRECEIVE AND 
POST issued by the program results 
in the creation of a thread, which is 
then destroyed after the receive has 
been satisfied. So if [MC JRE¬ 
CEIVE AND POST is used to 
save threads or improve perfor¬ 
mance, consider creating an individ¬ 
ual thread and issuing 
[MCJRECEIVE AND WAIT 
verbs on that thread. 

8: Minimize use of the 
GET TYPE, [MCJGET ATTRI¬ 
BUTES, and DISPLAY verbs. 

TPs should know most of this infor¬ 
mation already. If these verbs are 
called, their returned parameters 
should be kept in local program vari¬ 
ables for later use as required. 
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In OS/2 EE version 1.2, the DIS¬ 
PLAY verb returns a superset of the 
information returned on the 
GET TYPE and [MC JGET AT¬ 
TRIBUTES verbs. If there is a 
choice between using DISPLAY or 
[MC JGET ATTRIBUTES (for 
example, only the network name is 
desired), use [MCJGETATTRI- 
BUTES. 

These verbs may prove to be help¬ 
ful on error paths, so don’t omit 
them entirely. For example, if a re¬ 
turn code indicates that a verb was 
issued in the wrong state, the DIS¬ 
PLAY verb can be issued to find 
the current state of the conversation. 

9: Use the [MC JFLUSH verb ju¬ 
diciously. 

[MC JFLUSH forces APPC to 
send the data in its internal buffers, 
even though those buffers may not 
be full. Unless the partner needs 
the data immediately, let APPC de¬ 
termine when to send the data. 

An example of a situation in which 
[MC JFLUSH would not be benefi¬ 
cial is when multiple 
[MCJSENDJDATA verbs are is¬ 
sued. APPC normally fills its buff¬ 
ers before sending. If the maximum 
frame size is 2 KB and each 
[MC JSENDD AT A is 1 KB long, 
flushing the buffers would double 
the number of transmissions and 
leave the buffers only 50 percent uti¬ 
lized. 

If the TP issues an 
[MCJSEND_DATA verb and then 
plans on issuing no verbs for 
awhile, it should probably issue a 
[MC JFLUSH verb to clear its buff¬ 
ers, so the data can be used by the 
remote TP. 

10: Send many complete logical re¬ 
cords with one verb. 


When using basic conversations, 
send as much data as possible on 
each SEND J) AT A. If the data is 
available (and less than 64 KB in 
total size), the program should send 
multiple logical records with a sin¬ 
gle SEND J) AT A verb. However, 
avoid splitting logical records 
across verbs. 

11: Receive as much data as possi¬ 
ble on each Receive verb. 

Allocate a large memory block for 
incoming data, and receive as much 
data as possible on each Receive 
verb: 

[MCJRECEIVE AND POST, 
[MCJRECEIVE AND WAIT, or 
[MCJRECEIVE IMMEDIATE. 

When using basic conversation 
verbs, specify fill(BUFFER) on the 
Receive verbs, instead of fill(LL). 
With fill(BUFFER), the TP can re¬ 
ceive multiple logical records with a 
single call to APPC. 

12: Minimize the number of param¬ 
eters set in each verb control block. 

a. If a field in a verb control block 
serves only as a “returned param¬ 
eter,” it does not need to be set 
to any value before each call. 

The primary and secondary re¬ 
turn codes, for example, are re¬ 
turned parameters that APPC 
does not examine on the call; it 
only sets them upon return. 

b. The tp id and conv id are 
needed in all conversation verbs 
after the initial [MCJALLO- 
CATE or RECEIVE ALLO¬ 
CATE. If the TP reuses the 
same verb control block for all 
verbs in a conversation, it should 
not need to set the tp id and 
convjd before each call to 
APPC. 


c. Whether the verb is basic or 
mapped is a supplied parameter 
on all conversation verbs. If the 
verb control block is reused, a 
program can set the conversation 
type once at the beginning of the 
conversation, and not change it 
for the subsequent verbs on that 
conversation. 

Remember to set all reserved fields 
to zeros before calling APPC. 

13: Use a minimum number of seg¬ 
ments for the data buffers in the TP. 

Each different segment used for a 
data buffer incurs extra APPC over¬ 
head. Once APPC has been called 
with the address of a data buffer, 
APPC does not free the segment 
used for a data buffer until the OS/2 
process APPC was called in is termi¬ 
nated. Reuse the same data buffer 
segments, when possible. 

14: Convert names from ASCII to 
EBCDIC once. 

For parameters such as tp_name 
and mode name, make the calls to 
the CONVERT verb once at the be¬ 
ginning of the program, and save 
the converted names for later use. 

15: Minimize the use of Iog_data 
and pipdata. 

The implementation of APPC on 
some machines may require the use 
of pip_data to perform initializa¬ 
tion. Similarly, some transactions 
may depend upon a transfer of 
I°g_data. But, in general, the infor¬ 
mation exchanged with these param¬ 
eters (on the DEALLOCATE, 
SEND ERROR, and [MCJALLO- 
CATE verbs) can probably be han¬ 
dled in a more efficient manner by 
the two TPs. 
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16: Have multiple conversations se¬ 
rially reuse a session. 

Sessions can be expensive to bring 
up and take down, especially since 
links may need to be activated. 

Reuse sessions, if possible. 

17: Keep conversations active 
when using APPC frequently. 

APPC sets aside internal buffers 
and control blocks each time a con¬ 
versation is allocated, and frees 
these each time a conversation is 
deallocated. If there is no conten¬ 
tion for a session, keep a running 
conversation active for as long as it 
is needed - then deallocate it as 
soon as the TP has finished with it. 

However, by following this sugges¬ 
tion in a simple-minded manner, per¬ 
formance can actually be degraded. 
When APPC allocates the control 
blocks necessary for a conversation, 
this memory is no longer available 
for other use in the system. As the 
number of conversations increases, 
the available system memory can de¬ 
crease, causing excessive swapping 
on either machine. This can espe¬ 
cially be a problem on some remote 
machines with operating systems 
other than OS/2. If there are long 
pauses between a program’s use of 
APPC, it may be better to dealloc¬ 
ate and later reallocate a conversa¬ 
tion. 

In some APPC implementations on 
other machines, the attach overhead 
(that is, the overhead of processing 
an ALLOCATE issued by the part¬ 
ner) is so large that it is expensive 
to issue DEALLOCATE for any¬ 
thing less than a disaster. Here are 
a few trade-offs to consider. 

• Consider the partner’s attach 
overhead. The time to process 
an incoming allocation request is 


relatively fast for APPC/PC (for 
PC-DOS), APPC on OS/2, and 
APPC on the RT PC. This pro¬ 
cessing time is reasonable on 
CICS, although CICS has been 
optimized for attaching LU type 
0 and LU type 2 transactions 
from financial terminals or 3270 
terminals. The attach processing 
in the System/38 and the AS/400 
appears to be somewhat slower. 
As with anything, performance 
may vary. 

• Consider the number of sessions 
required. If the application main¬ 
tains a conversation for an indefi¬ 
nite period, other applications 
will need their own sessions. If 
there is a chance that other appli¬ 
cations will use an LU to commu¬ 
nicate with applications serviced 
by the partner LU, they may be 
forced to wait for a session. 

• Consider processing delays. If 
there is a long delay, other appli¬ 
cations may be able to utilize the 
network resources. If the delay 
is very short, deallocating the 
conversation may cause excess 
system processing. 

• Consider the server resource utili¬ 
zation, when using APPC in a 
server-requester relationship. By 
deallocating the conversation, the 
partner can allocate the program 
space, buffers, and control blocks 
to other needy requesters. 

• Finally, there’s the cost of the 
link when trying to improve per¬ 
formance. Long-distance tele¬ 
phone calls over switched SDLC 
links usually mean that sessions 
and conversations should be de¬ 
signed to be as short as possible. 

18: Deallocate only one side of a 

conversation. 


Either side may deallocate a conver¬ 
sation; this terminates the conversa¬ 
tion for both partners. If any verb 
in the local TP receives one of the 
five DEALLOCATE primary return 
codes, it can safely assume the con¬ 
versation is over; the local TP does 
not need to spend time issuing a 
[MCJDEALLOCATE verb. 

These primary return codes are: 

0005 DEALLOC_ABEND 

0006 DEALLOC_ABEND_PROG 

0007 DEALLOC_ABEND_SVC 

0008 DEALLOC_ABEND_TIMER 

0009 DEALLOC NORMAL 


19: Avoid using one of the 
ABEND types on the 
[MCJDEALLOCATE verb. 

The type(FLUSH) supplied parame¬ 
ter is faster than the other types on 
the [MCJDEALLOCATE verb. In 
addition to causing two internal mes¬ 
sage exchanges with the partner, is¬ 
suing a [MCJDEALLOCATE 
verb with one of the ABEND types 
causes APPC to write an entry to 
the Communications Manager error 
log. 

20: Take down conversations be¬ 
fore issuing TP_ENDED. 

Issuing a TP_ENDED verb causes 
a DEALLOCATE with 
type(ABEND_PROG) to be issued 
for each active conversation. As 
previously mentioned, issuing a 
[MCJDEALLOCATE verb with 
one of the ABEND types causes 
two internal message exchanges 
with the partner and an error log 
entry to be written. 

21: Minimize use of TPJENDED 
with type(HARD). 

In OS/2 EE Version 1.2, issuing the 
TP ENDED verb with 
type(HARD) causes all sessions 
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being used by the TP to be taken 
down. If these sessions are to be 
used again, they will have to be 
brought back up again. 

TP_ENDED with type(SOFT) does 
not affect the sessions. 

22: Use the performance advan¬ 
tages available through the compiler 
and linker. 

A number of the features in the 
OS/2 compilers and linkers are de¬ 
signed to speed program execution. 

A short summary includes: 

a. Enable as many compiler and 
linker command-line optimiza¬ 
tions as possible. For example, 
with the IBM C/2 compiler, use 
the /G2 compiler flag to enable 
the machine instruction set for 
the 80286, 80386, and 80486 pro¬ 
cessors. Also, consider compil¬ 
ing with the /Ox option, which 
enables all compiler optimiza¬ 
tions. We suggest testing the 
program both without any optimi¬ 
zations and with optimizations; 
unfortunately, the optimizations 
may introduce subtle runtime er¬ 
rors. 

b. Use as small a memory model as 
possible. Four-byte pointers 
incur more than twice the cost of 
two-byte pointers. If the code 
and data can each fit in 64 KB 
segments, use the small memory 
model. 

c. Declare variables in registers. 
Many compilers implicitly use 
registers for loop counters inside 
of loops; consider explicitly 
using registers for variables - 
especially pointers - that are fre¬ 
quently used in a given proce¬ 
dure. 

d. Compile using the Pascal func¬ 
tion-calling convention; it is 


slightly faster than the standard 
way function arguments are 
pushed and popped in the C lan¬ 
guage. For example, with the 
IBM C/2 compiler, the /Gc op¬ 
tion causes all functions not 
marked with the cdecl keyword 
to be called using the Pascal call¬ 
ing convention. 

e. Use macros instead of proce¬ 
dures for small code routines 
that are executed frequently. 

This is especially effective when 
a routine is called from inside a 
loop. A good candidate for 
using a macro is a loop of re¬ 
peated calls to a procedure to 
send data (that is, the called pro¬ 
cedure sets up a verb control 
block, calls APPC, and examines 
the return code). Using macros 
may make the size of the result¬ 
ing program larger, depending 
upon how often a routine is 
called and how big it is. 

The following items, 23 through 25, 
do not have as much effect on per¬ 
formance as those previously men¬ 
tioned. Programs probably should 
not be restructured or their usability 
reduced to take advantage of these. 

23: Use basic conversation verbs. 

Mapped conversation verbs, while 
easier to use, require slightly more 
overhead inside APPC; the best we 
have seen is a 3.5-percent improve¬ 
ment in using basic conversation 
verbs rather than mapped in a one- 
to-one comparison. But, basic con¬ 
versation verbs allow sending 
multiple logical records on each 
call, reducing the calls to APPC. 

24: Have multiple conversations se¬ 
rially reuse a TP. 

APPC incurs a cost for internally 
managing the buffers associated 


with a TP. Let several conversa¬ 
tions serially use a single TP, when¬ 
ever possible. 

25: Use names that differ early in 
the characters they use. 

APPC can internally compare 
names faster if their characters dif¬ 
fer early in the name. For example, 
use the names “ABC” and “XYZ” 
instead of the names “XYZ01" and 
”XYZ02." This applies to LU 
names, mode names, TP names, 
passwords, and user IDs. 

While this does not save much in 
APPC performance, many staff- 
hours can be saved in the long term 
by choosing good names the first 
time. The following paper gives 
some excellent guidelines to con¬ 
sider when choosing names in a net¬ 
work: 

D. Libes, “Choosing a Name for 
Your Computer,” Communica¬ 
tions of the ACM , 32, 11, No¬ 
vember 1989, pages 1289 - 1291. 

Using OS/2 Effectively 

Because every system will probably 
be set up a little differently, we 
can’t make specific recommenda¬ 
tions on how to use OS/2, but here 
are a few guidelines. 

1: Minimize OS/2 swapping to 
disk, whenever possible. 

Calculate the storage required for 
OS/2, APPC, and other active fea¬ 
tures, using the guidelines described 
in the System Administrator s Guide 
and the Information and Planning 
Guide. Make sure that at least this 
much random access memory 
(RAM) is installed in the machine. 

2: Set aside as much DISKCACHE 
memory as is reasonable. 
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Specify the DISKCACHE size, in 
bytes, in the CONFIG.SYS file. 

The amount of memory specified 
should be part of the calculation of 
required OS/2 memory, as pre¬ 
viously described. 

3: Minimize the number of threads 
the program creates. 

Do not create more threads than nec¬ 
essary to do the work needed by the 
OS/2 program. This avoids the cost 
in OS/2 of task switching among 
the threads. 

4: Avoid starving incoming and out¬ 
going DLC traffic. 

When processing verbs, APPC runs 
on the thread of the calling pro¬ 
gram. When processing incoming 
and outgoing data, APPC runs on 
the thread of the DLC device driver. 
Hard loops of verb calls at the API 
can delay the task switch needed to 
handle incoming or outgoing data 
for any active TP. 

For example, avoid a hard loop of 
unsuccessful [MCJRECEIVE JM- 
MEDIATE verbs in the TP. There 
are a couple of ways to do this: 

• Periodically make a call to 
DosSleep (with a short sleep pe¬ 
riod) to give APPC a chance to 
handle the data sooner. 

• Replace the 

[MCJRECEIVE IMMEDIATE 

verb with a 

[MCJRECEIVE AND POST 
verb, and then loop on 
DosSemWait with a non-zero 
timeout value specified on the 
DosSemWait function call. This 
incurs less total overhead than a 
loop with DosSleep and 
[MCJRECEIVE IMMEDIATE 
and the non-zero timeout still al¬ 
lows other threads the time to run. 


5: Avoid the time-critical priority 
class. 

Any OS/2 program can use the Dos- 
SetPrty function call to change its 
own priority within the system. 

There are three priority classes, 
numbered from 1 (lowest) to 3 
(highest). Number 3 is the time- 
critical priority. Using time-critical 
priority disturbs the balance be¬ 
tween handling user requests (for ex¬ 
ample, keyboard or mouse input) 
and incoming and outgoing data. 

Its use with APPC is not recom¬ 
mended. 

Examples of using the OS/2 priori¬ 
ties to fine-tune the multitasking be¬ 
havior of programs are given in the 
articles: 

M.J. Minasi, “OS/2 Notebook: 
Getting Your Priorities Straight,” 
Byte , 14, 12, November 1989, 
pages 159-162. 

M.J. Minasi, “OS/2 Notebook: 
OS/2 Multitasking Revisited,” 
Byte , 14, 13, December 1989, 
pages 133-136. 

The second article shows how one 
child program can run 100 times 
faster than another by changing the 
parameters on the DosSetPrty func¬ 
tion call. 

6: Determine whether remotely 
started programs run in the fore¬ 
ground. 

If a remotely started OS/2 program 
(that is, a program started because 
of an arriving allocation request 
from its partner) does not require in¬ 
teraction with a user, write the pro¬ 
gram so that it can be run in the 
background. Screen I/O, whether in 
a text-based screen group or in a 
Presentation Manager window, can 
slow down data communications. 


However, a program that is visible 
on the screen has foreground prior¬ 
ity, and runs about 25 percent faster 
than the same program if it was not 
visible. If it does minimal I/O, its 
greatest cost is therefore the cost in 
OS/2 of creating and displaying a 
new window or screen group. 

It is advisable to configure a pro¬ 
gram to do screen I/O (see the Pro¬ 
gram Type field in the “Remotely 
Attachable Transaction Program pro¬ 
file”) while testing and debugging 
it; then later change the configura¬ 
tion and program so that it runs in 
the background with no I/O after it 
is debugged. 

Using Traces to Estimate 
Timings 

Because APPC performance de¬ 
pends on so many variables (such as 
the CPU speed, the amount of 
RAM, the OS/2 EE version, the 
DLC being used, and the other pro¬ 
grams running), no one can say how 
long a given verb will take to exe¬ 
cute on a system. However, the 
Communication Manager Trace Ser¬ 
vices has an easy way to get timings 
of each verb issued by a program. 

Activate the “APPC API trace,” 
using the DEFINE_TRACE com¬ 
mon services verb or the Trace Ser¬ 
vices panels. Run whichever 
transaction programs you have that 
should be timed. Whenever the pro¬ 
gram calls APPC, APPC writes the 
verb control block to the trace data; 
similarly, when APPC returns to the 
program, it writes the returned verb 
control block. These trace records 
contain a time stamp, with an accu¬ 
racy of hundredths of a second. By 
subtracting the time stamp of the 
API Request in the trace from the 
time stamp of the API Return, the 
duration of a verb can be roughly 
calculated. How much time the pro- 
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gram spends between its calls to 
APPC can similarly be estimated. 

To find the amount of time spent ex¬ 
changing data, trace the data for the 
DLC being used by the programs. 
Full directions on how to set up trac¬ 
ing and read the resulting trace re¬ 
cords are in the Programming 
Services and Advanced Problem De¬ 
termination for Communications. 

Tracing slows the overall execution 
time, so when not tracing, the pro¬ 
gram will naturally run faster. The 
tracing speed can be increased by 
changing the “trace truncation” 
length from its default of 0 - which 
means writing the entire control or 
data block to the trace - to a small 
number such as 16. Also, note that 
the resolution of the OS/2 clock is 
not as granular as 1/100th of a sec¬ 
ond, which may skew the timings 
somewhat. Finally, all APPC calls 
by all active transaction programs 
will be in the trace together, so be 
aware that the trace records may be 
interleaved for concurrent TPs. 

Look at the tp_id or conv_id to tell 
which program a trace record is for. 


Summary 

• Use large RUs and buffers for 
the DLCs and sessions. 

• Minimize flows needed for nego¬ 
tiation of values by careful con¬ 
figuration. 

• Bring up links and sessions early, 
so they do not have to be brought 
up by the TP. 

• Reuse sessions once they are es¬ 
tablished. 

• Minimize useless calls to APPC. 

• Combine functions in a single 
verb. 

• Use large send and receive data 
buffers. 

• Reuse data buffers and verb con¬ 
trol blocks. 

• Use the available compiler and 
linker optimizations. 

• Minimize disk swapping and task 
switching in OS/2. 

• Use the Communications Man¬ 
ager Trace Services to help esti¬ 
mate where the program is 
spending its time. 
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EASEL OS/2 
EE PROFS: 

Host Code 
Interface 

Clayton Arndt 
IBM Corporation 
Dallas , Texas 

This article presents a sample pro¬ 
gram written in EASEL for OS/2 
EE. The code is used to “auto¬ 
mate” the logon process to the 
PROFS application on a VM host, 
and to logoff from the host. 

EASEL for OS/2 EE is a highly pro¬ 
ductive migration and programming 
tool to help customers implement 
programmable workstations. 

EASEL Development allows users 
to produce graphical front ends on 
an OS/2 Extended Edition Program¬ 
mable Workstation to replace the 
3270 user interface of existing host 
applications. Additional application 
logic can also be programmed to 
add new workstation function while 
the existing host 3270 applications 
continue to run unchanged. 

EASEL Runtime executes these 
new front-end applications on an 
OS/2 Extended Edition Programma¬ 
ble Workstation. The front-end ap¬ 
plications developed with EASEL 
will conform to the Common User 
Access (CUA) guidelines of Sys¬ 
tems Application Architecture 
(SAA). EASEL uses OS/2 EE Com¬ 
munications Manager and Presenta¬ 
tion Manager facilities to provide 
both a productive programming and 
execution environment. 

Highlights of EASEL: 

• Facilities to develop and execute 


a graphic user interface that con¬ 
forms to the CUA Graphics 
Model for OS/2 EE users in addi¬ 
tion to the 3270 user interface of 
existing host applications for 
3270 terminal users 

• Development and Runtime prod¬ 
ucts 

— Interactive CUA screen layout 
facility that uses OS/2 Presen¬ 
tation Manager 

— High-level language that is 
block structured and event 
driven 

— Trace and debug facilities 

— Separately licensed runtime fa¬ 
cility 

• 3270 terminal emulation in the 
OS/2 Communications Manager 

• Facilities to add logic at the pro¬ 
grammable workstation without 
impacting existing 3270 host ap¬ 
plications or users of those appli¬ 
cations at 3270 terminal devices 

• Facilities to implement graphic 
user interfaces that can support 
higher productivity 

• National Language Support (NLS) 

EASEL 3270 Host Support 

EASEL interfaces with 3270 host 
applications through the OS/2 EE 
Communications Manager Emula¬ 
tion High Level Language Applica¬ 
tion Programming Interface 
(EHLLAPI). For the programmer’s 
benefit, an interface to EHLLAPI is 
supplied by the EASEL 3270 sup¬ 
port module. EHLLAPI functions 
are not directly callable from an 
EASEL program; instead, the 
EASEL 3270 module translates 


3270 action routine calls into the ap¬ 
propriate EHLLAPI function calls. 
The 3270 action routines let the pro¬ 
grammer: 

• Emulate standard and special 
function keystrokes 

• Find the current cursor position 

• Monitor the Operator Information 
Area (OIA) for messages 

• Get the attributes and length of a 
field on the screen 

• Get the contents of a single field 
or an entire line from the screen 

• Place text into a field with or 
without padding blanks 

• Read screen contents, or a por¬ 
tion of any screen, into windows 

EASEL can connect up to five host 
sessions, depending upon the config¬ 
uration of the host line and of Com¬ 
munications Manager. EASEL can 
also disconnect previously con¬ 
nected host sessions in any order. 

A description of the support pro¬ 
vided by the EASEL 3270 module 
may be found in Appendix C of the 
EASEL OS/2 EE Developer s Guide 
(SC38-7034). 

EASEL Host Programming 
- FIELDS Utility 

The EASEL Development package 
includes a FIELDS utility for map¬ 
ping the 3270 host screens to deter¬ 
mine the starting and stopping 
locations of fields on the screen and 
the attributes associated with each 
field. For example, the programmer 
analyzes the host screen currently 
displayed in the 3270 Terminal Em¬ 
ulation session “B” by entering the 
following command at the OS/2 
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screen prompt: 

fields -sB profs.fld 

The “-s” option indicates that the re¬ 
port is to be generated for the termi¬ 
nal session represented by the 
specified single-letter short session 
name (in this case, session “B”). 

This parameter defaults to the first 
session. It is recommended that this 
parameter always be specified when 
Communications Manager is config¬ 
ured for more than one session. 

The parameter “profs.fld” is simply 
the name of the ASCII text file into 
which the programmer wants the 
FIELDS output to be written. Any 
valid OS/2 filename can be substi¬ 
tuted. If a file name is not given, 
the results are sent to the worksta¬ 
tion display. 

Running the FIELDS utility against 
the previously mentioned host 
screen will produce the output 
shown in Figure 1. 

The field report lists the session 
name at the top and displays a dupli¬ 


cate image of the host screen. This 
is followed by the total field count 
on the screen and the current cursor 
position. Next, the field summary 
describes each of the fields found 
on the screen: 

• Field number 

• Starting coordinates 

• Ending coordinates 

• Length of field (characters) 

• Field attributes: unprotected, nu¬ 
meric, nondisplay, modified 

• First 30 characters found in the 
field 

This summary shows the program¬ 
mer which fields are fixed and 
which can be filled in with informa¬ 
tion. In addition, each field can be 
referenced in the EASEL program 
by the field number listed in the re¬ 
port, or the coordinates of the field 
may be used as the basis for interac¬ 
tion. The EASEL program pre¬ 
sented later in this article shows 


how the contents of a field can be 
used to determine which host screen 
is currently displayed. 

Developing the EASEL Host 
Interface 

The programmer developing the 
EASEL interface to the host applica¬ 
tion should have a thorough knowl¬ 
edge of the structure and flow. It 
will be necessary to supply logic in 
the EASEL code to handle all antici¬ 
pated screens. The FIELDS utility 
can be used to make reports of the 
structure and contents of each host 
screen. 

Host screens that are dynamically 
generated (that is, the contents are 
not statically fixed) present a differ¬ 
ent problem. Here the FIELDS util¬ 
ity would not be useful because the 
number, location, and content of the 
fields can change as the host appli¬ 
cation progresses. For dynamic 
screens, EASEL can read the entire 
screen into a textual region and can 
then scan through the region, search¬ 
ing for keyword(s) that indicate the 
desired information. 
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FIELDS utility - Version HI.20 (HLLAPI) 

Copyright (C) 1987,1988,1989 Interactive Images, Inc. 

All Rights Reserved. 

Session short name = B 

00000000011111111112222222222333333333344444444445555555555666666666677777777778 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


VIRTUAL MACHINE/SYSTEM PRODUCT 


WELCOME TO THE 


M & D SE REGION I/S SUPPORT SERVICES NETWORK 
This system is restricted to IBM management 
approved business purposes only. 

ENTER: VMEXIT to return to the initial 
selection screen. 

Fill in your USERID and PASSWORD and press ENTER 
(Your password will not appear when you type it) 

USERID ===> 

PASSWORD ===> 

COMMAND ===> 

RUNNING XXXXXXXX 

Screen contains 30 fields. 

Cursor is at [20,16]. 


Field summary: Unp=Unprotected, Num=Numeric, Nds=Nondisplay, Mod=Modified 


Fid# 


Start 

End 

Len 

Unp 

Num Nds Mod 


First 30 Characters 

1 

1 

[1,2] 

[1,47] 

46 



1 

1 


[VIRTUAL MACHINE/SYSTEM PRODUCT 

2 

1 

[1,49] 

[2,17] 

49 



1 

1 


[ 

3 

1 

[2,19] 

[3,17] 

79 



X | 

1 


[ 

4 

1 

[3,19] 

[4,17] 

79 



x I 

1 


[ 

5 

1 

[4,19] 

[5,17] 

79 



x I 

1 


[ WELCOMETOT 

6 

1 

[5,19] 

[6,17] 

79 



x | 

1 


[ =-== =========== ==== 

7 

1 

[6,19] 

[7,17] 

79 



x | 

1 


[ ========= =======_=_== ==_=_ 

8 

1 

[7,19] 

[8,17] 

79 



x I 

1 


ii 

it 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

n 

ii 

ii 

ii 

ii 

9 

1 

[8,19] 

[9,17] 

79 



x i 

1 


ii 

ii 

ii 

n 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

10 

1 

[9,19] 

[10,17] 

79 



x 1 

1 


ii 

n 

ii 

ii 

ii 

ii 

ii 

ii 

ii 

n 

n 

n 

ii 

n 

ii 

ii 

ii 

11 

1 

[10,19] 

[11,17] 

79 



x | 

1 


ii 

n 

ii 

n 

n 

ii 

ii 

it 

ii 

ii 

ii 

ii 

ii 

n 

12 

i 

[11,19] 

[12,17] 

79 



x | 

1 


[ =======_= ==__===_=__= __== 

13 

1 

[12,19] 

[13,17] 

79 



x | 

1 


n 

ii 

ii 

ii 

n 

ii 

n 

ii 

ii 

ii 

ii 

ii 

ii 

n 

n 

ii 

ii 

ii 

it 

ii 

ii 

ii 

ii 

it 

14 

1 

[13,19] 

[14,17] 

79 



x I 

1 


[M & D SE REGION I/S SUPPORT SE 

15 

1 

[14,19] 

[15,17] 

79 



x | 

1 


[This system is restricted to I 

16 

1 

[15,19] 

[16,17] 

79 



x I 

1 


[approved business purposes onl 

17 

1 

[16,19] 

[16,31] 

13 



x 1 

1 


[ENTER: VMEXIT] 

18 

1 

[16,33] 

[17,17] 

65 



x i 

1 


[to return to the initial 

19 

1 

[17,19] 

[17,80] 

62 



x I 

1 


[selection screen. 

20 

1 

[18,2] 

[18,80] 

79 



x 1 

1 


[Fill in your USERID and PASSWO 
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[USERID ===>] 
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[PASSWORD ===>] 
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27 
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28 
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[COMMAND ===>] 
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1 
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[ 

30 
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1 

1 


[RUNNING XXXXXXXX ] 


Figure 1. PROFS Field Utility 
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Remember that the EASEL inter¬ 
face is built within and runs within 
the OS/2 interface in the program¬ 
mable workstation. No changes to 
the host application are required. 

An Example of an EASEL 
3270 Interface 

Figures 2a through 2f contain an 
EASEL program that provides a 
graphical CUA interface to the 
PROFS system running on a VM 
host. Its application requirements 
are simple: 

• Show the PROFS screens in an 
OS/2 Presentation Manager win¬ 
dow 

• Use Communications Manager 
session B (defined as a Model 2 
screen size - 24 x 80) 

• Provide a means to: 

— Log on to the host - enter user 
ID and password 

— Log off from the host 

Direct entry of data to PROFS is 
not required; this interface simply 
provides a means of logging on and 
off from PROFS. 

To use a different session, copy the 
short name to the CMSession con¬ 
stant. Be sure that this session is at 
the initial PROFS logon screen. 
After compiling and running, the 
current screen image from the speci¬ 
fied session is read and displayed. 

To logon to the host, select the Start 
Host option from the action bar. A 
dialog box requesting the user ID 
will appear. Clicking on CANCEL 
will cancel the logon process. Typ¬ 
ing in the ID and clicking on 
ENTER will cause the logon to be 


processed. The ID entered will be 
echoed on the host screen image for 
a second. 

Next, a dialog box requesting the 
user password will appear. This 
box has a “protected” entry field so 
the password will not show. Type 
the password and select ENTER. A 
message will appear stating that the 
host connection is being established. 

While waiting for the connection, 
PROFS can take a number of sec¬ 
onds to perform the initial DASD 
linking, message displaying, and so 
forth, before actually reaching the 
main PROFS menu. The program 
will allow 30 seconds for this activ¬ 
ity to be performed. If the time 
limit expires, a “no-connection” 
message will be displayed. This 
sample code does not carry the 
error-checking any further; you 
could hit the refresh button to bring 
up the menu, or end the program, 
logoff, and try again. 

To logoff, select the Logoff Host 
pulldown in the action bar when the 
PROFS main menu is displayed. 

The string “logoff’ will be dis¬ 
played and the PROFS logon screen 
should reappear in a few seconds. 

The refresh button simply rereads 
the current PROFS screen into the 
textual region. The exit button in 
the upper right of the action bar 
ends the program. 

The figure containing the program 
shows the code in the left column: 
the explanation of the code is in the 
right column. In a screen display of 
such a program, comments would 
be preceded by a pound sign (#). In 
this example, the static text in the di¬ 
alog boxes may be shown as 
wrapped, but in an actual program 


should be entered as a single line. 

Conclusion 

The code in this EASEL PROFS in¬ 
terface is simple and is limited in 
function. There are many enhance¬ 
ments that could be added, for ex¬ 
ample: 

• Pulldowns to send PF keys to the 
host 

• Pulldowns to send other attention 
keys (for example, Enter, Clear, 
Reset) 

• The ability the type directly into 
the textual region and send the 
data to the host 

• Single functions that navigate 
through several host screens with¬ 
out additional user interaction 
(for example, retrieving mail or 
generating a list of all files in per¬ 
sonal storage). 

EASEL is a great tool for generat¬ 
ing easy-to-use, interactive inter¬ 
faces to optimize your host 
applications. 
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screen size device units 

modul e M3270 Specification for the EASEL 3270 module 


string constant Logoffstring 
string constant Waitingstring 
host connection ...” 
string constant GiveUpString 

host connection failed.” 
string constant CMSession 


is “logoff” 
is “Waiting for 

is “Sorry ... 

is “B” 


Declaration and initialization of string constants used in 
the EASEL interface. (WaitingString and GiveUpString 
are shown here as wrapped but should be entered as a sin¬ 
gle line.) 


string variable UserlD 
string variable Passwordstring 

action bar ProfsBar is 

pulldown StartHost text “-Start Host” 
choice StartPROFS text "Start PROFS” 
end pulldown 

disabled pulldown LogoffHost text “-Logoff 
choice LogoffPROFS text “Logoff PROFS” 
end pulldown 

button Refresh text “-Refresh” 
button Exit text “-Exit” 
end action bar 


Declaration of variables used in the interface 

Define the action bar to appear at the top of the interface 
window. Two pulldowns will appear: 

„ pulldowns choices 

Start Host Start PROFS 

Logoff Host Logoff PROFS 

In addition, the action bar contains two buttons: Refresh 
(to re-read the current host screen into the text window) 
and Exit (to end the program). 


primary textual region Profs 
size 580 280 
at position 30 50 
yellow foreground 
size border 
title bar “PROFS” 
system menu 
horizontal scroll bar 
vertical scroll bar 
action bar ProfsBar 
minimize button 
maximize button 
font “asc59” 

enabled invisible modal dialog box IDBox 
size 120 102 
at position 128 35 
dialog border 
title bar “Host User ID” 
enabled visible static text IDText 
size 102 41 
at position 9 54 
in IDBox 
left align 
top align 
word wrap 

text “Please enter your host user ID. Press 
ENTER to complete, or press CANCEL to quit.” 
disabled visible entry field IDField 
size 80 12 
at position 20 31 
in IDBox 

text size 8 columns 
left align 


Primary Region Definition: 

The primary window is defined as a textual region with 
the title “PROFS”. The window has a yellow foreground 
(the color in which the text will be displayed), and a 
black background (by default). The window also sports 
an OS/2 PM sizeable border, a system menu, and PM hor¬ 
izontal and vertical scroll bars. The previously defined ac¬ 
tion bar is included, as are minimize (default icon when 
minimized) and maximize buttons. The font “asc59" is 
an EASEL fixed-cell font with a total size of 7 x 11. This 
is the font used when displaying text within the window. 

Dialog Box Object Definition(s): 

The first dialog box is called IDBox. It has a dialog bor¬ 
der and a title bar which displays “Host User ID”. A 
static text field inside the dialog box provides instructions 
to the user to enter the ID into the entry field. (The static 
text in the dialog boxes may be shown here as wrapped, 
but should be entered as a single line.) An entry field 
called IDField is provided to accept the user’s input: this 
field is limited to eight characters maximum. Two push 
buttons are also provided: one labeled OK (the default 
push button taken when the ENTER key is pressed) and 
one labeled Cancel (the cancel push button taken when 
the ESC key is pressed). 


Figure 2a. Sample EASEL Program 
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enabled visible default push button OK 
size 38 12 
at position 11 3 
in IDBox 
text “-Enter” 

enabled visible cancel push button Cancel 
size 38 12 
at position 60 3 
in IDBox 
text “-Cancel” 


enabled invisible modal dialog box PasswordBox 
size 120 102 
at position 128 35 
dialog border 
title bar “Host Password” 

enabled visible static text PasswordText 
size 102 41 
at position 9 54 
in PasswordBox 
left align 
top align 
word wrap 

text “Please enter your host password. The 

entry field is protected so that the password 
will not show.” 

enabled invisible entry field PasswordField 
size 50 12 
at position 29 31 
in PasswordBox 
text size 8 columns 
left align 

disabled visible entry field DummyField 
size 50 12 
at position 29 31 
in PasswordBox 
text size 30 columns 
left align 

disabled visible group box ThinLine 
size 1 12 
at position 32 33 
in PasswordBox 

enabled visible default push button OK 
size 38 12 
at position 11 3 
in PasswordBox 
text “-Enter” 


The second dialog box is called PasswordBox. It also has 
a dialog border and a title bar which displays “Host Pass¬ 
word”. A static text field within the box instructs the user 
to enter the host password and reassures the user that the 
password will not be displayed. Two entry fields are de¬ 
fined in the dialog box: the real (active) entry field is 
called PasswordField. The other entry field is called 
DummyField and is positioned directly over the Password- 
Field. This has the effect of covering up PasswordField 
so that the password will not be displayed. To make it ap¬ 
pear to the user that the top entry field is active, a very 
thin group box is positioned within DummyField to simu¬ 
late the appearance of the text cursor. Finally, a default 
push button labeled OK is provided to allow the user to 
complete the password entry. 


action ShowProfsCursor is 
action GetCursorPosition 
add to Profs 

move to column Column line Row 
make Profs cursor visible 


action ErrorMessage is 
clear Profs 
add to Profs 

move to column 20 line 10 
insert at cursor GivellpString 


Action/Subroutine Definitions: 

action ShowProfsCursor - Executes the 3270 action Get 
CursorPosition, which returns the current position of the 
host cursor in the global variables Column and Row. 
Within the text window Profs, the textual cursor is moved 
to these coordinates and is made visible. 

action ErrorMessage - This action is called in response 
to a timeout on a host action. The textual region Profs is 
cleared and the message in GiveUpString is inserted into 
the window. 


Figure 2b. Sample EASEL Program 
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subroutine GetUserID(string:String) is 
make IDBox visible 
activate IDField 
clear IDField 
begin guarded 

response to OK in IDBox 

copy (text of IDField) to String 
make IDBox invisible 
leave block 

response to Cancel in IDBox 
copy to String 

make IDBox invisible 
leave block 
end 

subroutine GetUserlD - This subroutine is called when 
the interface needs to request the user’s ID for the host. 

The IDBox dialog box is made visible and the text cursor 
is moved to the IDField entry field. In addition, the IDF¬ 
ield is cleared to remove any text remaining from a previ¬ 
ous entry. A guarded block is set up to allow a response 
to be taken to the buttons in the dialog box. If the user 
clicks on the OK push button, the text typed into the IDF¬ 
ield is copied to the subroutine parameter String (which is 
coincidentally a string variable), the IDBox is made invisi¬ 
ble, and the guarded block is left. If the user clicks on 
the Cancel push button, a null string is copied to the 
parameter String, the IDBox is made invisible, and the 
guarded block is left. 

subroutine GetPassword(string:String) is 
make PasswordBox visible 
activate PasswordField 
clear PasswordField 
begin guarded 

response to OK in PasswordBox 

copy (text of PasswordField) to String 
make PasswordBox invisible 
leave block 
end 

subroutine GetPassword - This subroutine is called 
when the host is ready to receive the user's password. 

The PasswordBox dialog box is made visible on the 
screen, and the PasswordField entry field is activated and 
is cleared of any residual text. Remember from the defini¬ 
tion of the controls in PasswordBox that the DummyField 
entry field overlays the PasswordField, so the user will 
not see the password as it is being entered. A guarded 
block is set up to allow a response to be taken to the push 
button in the dialog box. When the user has finished en¬ 
tering the password, clicking on the OK push button 
causes the text in PasswordField to be copied to the sub¬ 
routine parameter String. The PasswordBox is then made 
invisible and the block is left. 

response to start 

copy CMSession to SessionName 
action Init3270 
copy Profs to TextRegionName 
action ReadScreen 

Response Definitions: 

response to start - This is the initial response taken 
when the EASEL interface is first run. The short session 
name contained in the constant CMSession is copied to 
the global variable SessionName. The 3270 module is 
then started by calling Init3270. Profs is established to be 
the textual region into which the screens will be read, and 
the initial host screen is copied in. By default, the 3270 
module is set up to use a Model 2 (24 x 80) host screen. 

response to item StartPROFS in Profs 

response to item StartPROFS in Profs - This rather 
lengthy response contains the logic for logging on to the 
host. Comments are embedded within the response to as¬ 
sist in explaining the logic of the code. 

disable item StartHost in Profs 
enable item LogoffHost in Profs 

Change availability of items in the action bar. 

action ScanScreen 
action ShowProfsCursor 

Read current host screen into textual region and show cur¬ 
sor. 

call GetUserlD(UserlD) 

Call the subroutine GetUserlD to query the user for the 
host ID. The result is returned in the string parameter 
UserlD. 


Figure 2c. Sample EASEL Program 
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if (UserlD != “”) then 

If the UserlD is not a null string (i.e. the user entered an 

ID and selected the OK push button), begin the logon. 

add to Profs 

insert at cursor UserlD 
wait 1 

Display user ID in textual region and wait one second (so 
that the user can see the ID being entered). 

copy UserlD to Keystrokes 

Copy the ID to the global variable Keystrokes in prepara¬ 
tion for sending the ID to the host. 

action DefineWatch 
copy 24 to WatchRow 
copy 61 to WatchCol 
copy "C” to WatchChar 
action WatchForChar 
copy 20 to SettleTime 
action WatchForNoX 
action EnterString 
copy 3000 to GiveUpTime 
action WatchAndWait 

Set up a watch to indicate when we are at the next screen 
(this screen requests the user’s password). The FIELDS 
utility was run previously against this next screen, and it 
was noticed that the string “CP READ” appeared in the 
field located at coordinates (24,61). The appearance of 
the character “C” at this location will be detected by the 
action WatchForChar and will serve to verify that the de¬ 
sired host screen is available. The watch will also wait for 
the “X” in the OIA to disappear. A characteristic of the 
host system is that the “X” may flicker while the screen is 
being updated; to prevent this flickering from giving the 
false indication that the host screen is ready, the value 20 
(0.2 sec) is copied to the global variable SettleTime. The 
entire watch is limited to the time specified in GiveUpT¬ 
ime (in this case, 3000 = 30 sec). If the watch conditions 
are not satisfied before the GiveUpTime expires, the 
watch will be considered unsuccessful. 

if (WatchGaveUp) then 

Test to see if the watch was successful. 

action ErrorMessage 
el se 

Watch unsuccessful - display error message to user. 

copy Profs to TextRegionName 
clear Profs 
action ScanScreen 

Watch successful - clear the Profs textual region and scan 
the new host screen for its fields. 

call GetPassword(PasswordString) 

Call the subroutine GetPassword to query the user for the 
host password. The password is returned in the subrou¬ 
tine parameter PasswordString. 

copy Passwordstring to Keystrokes 

Copy PasswordString to the global variable Keystrokes in 
preparation for sending the string to the host. 

add to Profs 

move to column 20 line 10 
insert at cursor Waitingstring 

Display a message in the Profs textual region indicating 
that the interface is waiting on the host. 

action DefineWatch 
copy 1 to WatchRow 
copy 78 to WatchCol 
copy “A” to WatchChar 
action WatchForChar 
action WatchForNoX 
action EnterString 
action WatchAndWait 

Define a watch (similar to the previous watch) to wait 
while the host processes the password. By running the 
FIELDS utility against the next anticipated screen (the 
PROFS main menu), the character “A” located in the 
field at coordinates (1,78) was selected as the indication 
that the next host screen is ready. The SettleTime and 
GiveUpTime from the previous watch are still in effect. 


Figure 2d. Sample EASEL Program 
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if ( WatchGaveUp) then 

Test to see if watch was successful. 

action ErrorMessage 
el se 

Watch unsuccessful - display error message to user. 

copy Profs to TextRegionName 
clear Profs 
action ReadScreen 
action ScanScreen 
action ShowProfsCursor 
end i f 
end if 

Watch successful - clear the Profs textual region and read 
in the current host screen. In addition, scan the host 
screen for its fields and show the text cursor in the textual 
region at the current cursor position. 

el se 

enable item StartHost in Profs 
disable item LogoffHost in Profs 
end i f 

This “else” is associated with the test to determine 
whether the user entered a user ID or cancelled the opera¬ 
tion (which returned a null string). The availability of the 
pulldowns in the action bar is changed so that only the 

Start Host pulldown is active. 

response to item LogoffPROFS in Profs 

response to item LogoffPROFS in Profs - This re¬ 
sponse is taken when the user selects the Logoff Host 
pulldown from the action bar. It is assumed that the user 
is at the PROFS main menu (where the logoff command 
would normally be issued). 

action ScanScreen 
action ShowProfsCursor 

Scan the host screen for its fields and activate the text cur¬ 
sor in the Profs textual region. 

disable item LogoffHost in Profs 
enable item StartHost in Profs 

Change the availability of the pulldowns in the action bar. 

add to Profs 

insert at cursor Logoffstring 
wait 1 

For the benefit of the user, insert the contents of the 
string constant Logoffstring into the textual region. Wait 
one (1) second so that the user can see the string. 

copy 50 to FieldNumber 

copy Logoffstring to FieldText 

copy false to Fill Flag 

By running the FIELDS utility against the PROFS main 
menu, it was noted that the input field at the bottom of 
the screen is designated by the number 50. This is the 
field into which the string “logoff’ (contained in the 
string constant Logoffstring) must be typed. The FillFlag 
is set to false because it is not necessary to pad the rest of 
the field with blanks. 

action WriteField 

The contents of the desired field are sent to the host. 

action DefineWatch 
copy 13 to WatchRow 
copy 19 to WatchCol 
copy “M”to WatchChar 
action WatchForChar 
action WatchForNoX 

A host watch is defined to determine when the host has 
finished processing the logoff command. By running the 
FIELDS utility against the intitial host logon screen (see 
Figure 1), a certain characteristic of that screen could be 
chosen for the watch. Notice that field 14 at coordinates 
(13,19) begins with the characters “M & D”. The charac¬ 
ter “M” at this location was chosen to indicate that this 
screen has been reached. The SettleTime and GiveUpT- 
ime from the previous watches are still in effect. 


Figure 2e. Sample EASEL Program 
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action PressENTER 
wait 2 

action PressENTER 
action WatchAndWait 

One of the characteristics of this host system is that the 
ENTER key must be pressed again before the initial 
logon screen is displayed. Therefore, after entering the 
“logoff’ string, this code will wait a couple of seconds 
and then press the ENTER key again before starting the 
watch for the next screen. 

if (WatchGaveUp) then 

Test to see if watch was successful. 

action ErrorMessage 
el se 

Watch unsuccessful - display error message to user. 

copy Profs to TextRegionName 
clear Profs 
action ReadScreen 
action ScanScreen 
action ShowProfsCursor 
end if 

Watch successful - copy the new host screen into the 

Profs textual region, and show the cursor at the current lo¬ 
cation. In addition, scan the new host screen to determine 
its fields for the next interaction. 

response to item Refresh in Profs 
clear Profs 

copy Profs to TextRegionName 
action ReadScreen 
action ShowProfsCursor 

response to item Refresh in Profs - This response is 
taken when the user clicks on the Refresh button in the ac¬ 
tion bar. It simply clears the Profs textual region and re¬ 
reads the current host screen; nothing is sent to the host. 

response to item Exit in Profs 
copy CMSession to SessionName 
action Disconnect 
action Stop3270 
exi t 

response to item Exit in Profs - This response to taken 
to the selection of the Exit button from the action bar. 

The 3270 module is stopped by calling the action 

Stop3270 and the interface is ended. Note that if the user 
selects Exit while the program is in the middle of the 

PROFS application, the EASEL interface will stop but 
PROFS will not. The session will be left alone. 


Figure 2f. Sample EASEL Program 
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PS/2 RPG II 
Application 
Platform and 
Toolkit 


Jim Weir 

IBM Corporation 

Boca Raton, Florida 

The RPG II Platform supports multi¬ 
ple users on a PS/2 running the 
OS/2 operating system. Up to eight 
ASCII workstations are supported 
by the Platform. A ninth user is 
supported on the VGA-attached dis¬ 
play on the PS/2 host system. The 
RPG II Platform also supports a 
total of 16 LAN-connected work¬ 
stations. A combination of ASCII 
and LAN workstations are sup¬ 
ported - up to a total of eight 
ASCII workstations and a system 
total of 16 workstations. 

The RPG II Platform is a prerequi¬ 
site for the IBM PS/2 RPG II 
Toolkit. The Toolkit is a separate 
product that allows RPG II applica¬ 
tion owners to migrate their Sys¬ 
tem/36 RPG II applications to the 
PS/2 RPG II Platform. The RPG II 
Platform and Toolkit together make 
available on the PS/2 the thousands 
of System/36 RPG II applications 
available in the marketplace today. 

Figure 1 shows the RPG Platform 
and the RPG II applications execut¬ 
ing on the PS/2 host. The Toolkit 
consists of: 

• RPG Compiler 

• Screen Design Aid 

• Screen Format Generator 


• RPG II Auto Report 

• Data File Utility List Creation 

• Development Support Utility 

OS/2 is the required operating sys¬ 
tem on the PS/2 host; OS/2 1.1 and 
1.2 are supported by Release 1.1 of 
the Platform. Both OS/2 Standard 
Edition and OS/2 Extended Edition 
(EE) are supported. The RPG II 
Platform includes a terminal man¬ 
ager that provides the multiuser sup¬ 
port. The terminal manager 
operates in conjunction with OS/2 
multitasking capabilities and adds a 
record locking capability to ensure 
data integrity when files are shared 


among multiple users. The Plat¬ 
form uses standard OS/2 EE LAN 
software to support LAN work¬ 
stations. 

The RPG II execution environment 
supports a subset of System/36 
OCL and SSP commands and in¬ 
cludes several key System/36 utili¬ 
ties. All System/36 file types are 
supported, including indexed, alter¬ 
nate index, and direct files. Back¬ 
ground processing is supported 
through a job queue facility. 

In addition to the workstation sup¬ 
port, two printers are supported 
{note: printers do not count as work¬ 
stations) - one connected through 


3151 ASCII 



Figure 1. PS/2 RPG II Application Platform 
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the parallel port and one connected 
through the serial port. The printers 
supported are the Proprinter™, the 
Quick writer®, and the 4224 model 
3X X. The ASCII display stations 
supported are the IBM 3151 ASCII 
display, any PS/2, the PC AT 339 
and the PC XT/286. All devices re¬ 
quire the IBM Enhanced Keyboard, 
and any mix of these devices is sup¬ 
ported (up to a total of eight). 

In the LAN configuration, the 
server must use OS/2 EE, either 1.1 
or 1.2. DOS and OS/2 workstations 
are supported on the LAN. These 
workstations can be supported with 
either the IBM PC Network or the 
IBM Token Ring. 

Figure 2 shows how the RPG II Plat¬ 
form conceptually functions with 
OS/2. Standard LAN hardware and 
software are required to connect the 
LAN workstations to the OS/2 LAN 
Server. The RPG II Platform uses 
this standard LAN support to 
download RPG programs across the 
LAN and provide file server support 
on the OS/2 EE Server. The RPG 
programs execute on the LAN work¬ 
station. In the ASCII configuration, 
the terminal manager manages the 
attached workstations and provides 
the multiuser support on top of 
OS/2. Attached PS/2 or PC work¬ 
stations operate in 3151 emulation 
mode provided by the Independent 
Workstation (IW) Program that is in¬ 
cluded with the RPG II Platform 
product. The 3151 Displays, Model 
3X or 4X, require a feature called 
the Cartridge for Multiuser System 
Attachment. The 3151 Model 5X 
and 6X do not require this feature. 

The execution environment and the 
terminal manager together require 
one OS/2 session. Each attached 
display station runs as a thread 
within the RPG terminal manager 
session. Figure 2 shows a total of 


four active RPG tasks running dif¬ 
ferent RPG II applications. Other 
OS/2 sessions may also be active, 
such as a 3270 communications ses¬ 
sion (with OS/2 EE) as well as 
other personal computer applica¬ 
tions. Figure 2 shows a PC Applica¬ 
tion running under the OS/2 
operating system independent of the 
RPG II Platform. 


The RPG II Platform is designed to 
utilize standard OS/2 interfaces and 
functions, such as print spooling, 
wherever possible. This means that 
compatibility with future releases of 
OS/2 is maintained. Attachments of 
the various devices supported by the 
Platform are shown in Figure 3. 

The Proprinter and Quickwriter can 
be attached to the parallel or the se- 
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Figure 2. RPG II Platform and Toolkit with OS/2 EE 
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rial port. The 4224 printer is sup¬ 
ported only through the PS/2 Serial 
Port. This standard serial port can 
be used to attach either a printer or 
one of the ASCII display stations. 

A two-workstation configuration, 
therefore, can be supported without 
any additional adapters by using the 
system display as one workstation 
and the standard serial port for the 
second workstation. The Proprinter 
would be attached through the paral¬ 
lel port and serve as the system 
printer. 

The Dual Async Adapter/A can sup¬ 
port up to two of any of the display 
stations, providing a four-worksta¬ 
tion configuration. Only one Dual 
Async Adapter/A is supported by 
the RPG II Platform. The standard 
Serial Port and the Dual Async 
Adapter/A support the RS232 inter¬ 
face, which allows the attached de¬ 
vice to be located up to 50 feet 
from the host PS/2. 

If more than four workstations are 
required, the Realtime Interface 
Coprocessor Multiport/2 Adapter 
must be used. It supports up to 
eight workstations. All eight work¬ 
stations can be attached via the 
RS232 interface, or optionally, up 
to four may be attached via the 
RS232 interface and up to four via 
the RS422 interface. The RS422 at¬ 
tachment allows the workstation to 
be located up to 4,000 feet from the 
host PS/2. The RS232 interface 
adapter supports a distance of 40 
feet. The Multiport/2 adapter and 
the Dual Async Adapter/A are mutu¬ 
ally exclusive; for example, the 
RPG II Platform will support either 
one of these adapters but not both si¬ 
multaneously. 

The Multiport/2 adapter should be 
considered even in a two- to three- 
workstation configuration where 


growth is anticipated. It is required 
if the distance between the host 
PS/2 and the attached display sta¬ 
tion must be greater than 50 feet. 

Utilities 

RPG II Platform utilities are: 

• Data File Conversion (DFC) Util¬ 
ity 

• Data Exchange Utility (DEU) 

• Data File Utility (DFU) 

• Sort Utility 

• Source Entry Utility (SEU) 

With the DFC Utility, RPG II data 
files can be converted into standard 
text files that can be used by DOS 
or OS/2 personal computer applica¬ 


Figure 3. RPG II Platform ASCII Attachment 


tions, such as spreadsheets or word 
processors. 

The DEU converts files from the 
EBCDIC file format of the Sys¬ 
tem/36 to the ASCII file format of 
the PS/2, and vice versa. With this 
utility, files that have been 
downloaded from a System/36 can 
be converted and used by the PS/2 
RPG II applications, and vice versa. 

DFU, as on the System/36, is an 
easy-to-use tool for processing files 
and generating reports without 
doing any programming. 

Sort and SEU provide the same 
functions as they do on the Sys¬ 
tem/36. 

Independent Workstation 
Program 

Also included with the RPG II Plat¬ 
form package is the Independent 
Workstation Program, which pro- 


Attachment Options 

Devices Supported 

PS/2 Parallel Port 

Proprinter 

Quickwriter 

PS/2 Serial Port 

RS232 

Up to 50 feet 

Printer 

3151 ASCII Display 

PS/2 

PC AT 339 

PC/XT 286 

Dual Async Adapter/A 

2 Dev ices/1 Adapter 

Not Supported w/Multiport/2 
RS232 

Up to 50 feet 

3151 ASCII Display 

PS/2 

PC AT 339 

PC/XT 286 

Realtime Interface Coprocessor 
Multiport/2 Adapter 

Up to 8 via RS232 

Up to 4 each RS232 (50 feet) 
and RS 422 

3151 ASCII Display 

PC AT 339 

PC/XT 286 
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vides the 3151 emulation capability 
and must be loaded on each of the 
attached PS/2 or PC workstations. 

In addition, the Independent Work¬ 
station Program enables “hotkey” 
capability to a stand-alone DOS or 
OS/2 application. This means that a 
user can access the RPG II applica¬ 
tions on the host PS/2 and “hotkey” 
to a DOS or OS/2 application exe¬ 
cuting on the Independent Worksta¬ 
tion; for example, running 
DisplayWrite for letter writing or 
other text work. 

Because the RPG II applications are 
upwardly compatible to the S/36, a 
PS/2 system with the Platform and 
Toolkit software can serve as a 
stand-alone programmer develop¬ 
ment system for System/36 applica¬ 
tions as well as for the PS/2. 
Programmers using the attached 
workstations can modify or create 
programs using the SEU or the 
DSU. RPG II programs can be en¬ 
tered, compiled and tested using the 
RPG II Platform and Toolkit. Once 
testing is satisfactory, RPG II pro¬ 
grams can be converted from ASCII 


Host System 


Memory (+ OS/2 Requirements) 

Base System 

400 KB 

JOBQ 

200 KB 

System Console 

200 KB 

Attached Workstation 

200 KB ea. 

Maximum for 8 


attached users 

= 2.5 MB 

Fixed Disk 


RPG II Platform 

6 MB 

RPG II Toolkit 

2 MB 

RPG II Applications 

? 

Independent Workstation (IW) 

Memory 


IW Program 

75 KB 

Fixed Disk 


IW Program 

50 KB 


Figure 4. RPG II Platform/Toolkit 
Resource Requirements 


to EBCDIC using the DEU, then 
taken to a S/36 for final compilation 
and testing. 

Figure 2 shows a PS/2 used as a de¬ 
velopment system for RPG II appli¬ 
cations. In this example, one 
workstation is running the Screen 
Design Aid (SDA), and two are 
using the DSU to create or modify 
RPG II source code. An RPG II 
compile has been initiated from the 
JOBQ, which executes as a separate 
OS/2 session. As mentioned pre¬ 
viously, other OS/2 sessions may 
also be initiated for other personal 
computer applications. 

Resource Requirements 

Figure 4 lists the minimum memory 
required to run the RPG II Platform. 
The Platform requires a minimum 
of 1 MB of memory in addition to 
the memory required by the specific 
OS/2 edition installed. This 1 MB 
of memory supports the VGA- 
attached display and one attached 
display station. Because each at¬ 
tached display station requires 200 
KB, 2.5 MB (in addition to the 
OS/2 requirement) is the maximum 
required to support eight work¬ 
stations. For performance reasons 
these memory requirements allow 
the RPG II Platform and associated 
application code to be resident in 
memory so that no swapping is re¬ 
quired. 

In LAN configurations, the OS/2 
EE Server should have a minimum 
of 8 MB of memory. OS/2 LAN re¬ 
questers (which must also use OS/2 
EE for the requester support) should 
have a minimum of 5 MB of mem¬ 
ory. DOS workstations on the LAN 
should have a minimum of 640 KB. 

The fixed-disk requirement for the 
RPG II Platform and Toolkit pro¬ 
grams is approximately 6 MB. The 


total fixed-disk requirements will be 
determined by the specific applica¬ 
tions and size of the customer’s data 
files. The RPG II programs and 
data files take up approximately the 
same amount of space on the PS/2 
as on the System/36. 

The Independent Workstation (IW) 
Program, running on the attached 
PS/2 or PC workstations, requires 
75 KB of memory and 50 KB of 
fixed-disk storage. For PS/2 disk¬ 
ette models, the IW program would 
be loaded at the beginning of the 
day, and then the diskette drive can 
be used for other PC applications as 
required. 

Summary 

The RPG II Platform adds an excit¬ 
ing capability for the Personal Sys¬ 
tem/2. By expanding the 
application base to include many 
successful and proven RPG II busi¬ 
ness applications, IBM can offer a 
greater variety of PS/2 solutions. 

By addressing the needs of small 
businesses, or small departments 
within larger businesses, the RPG II 
Platform and RPG II Toolkit offer 
new ways to meet customer needs. 
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The IBM 
Independence 
Series 
Products 

This is a description of the IBM 
products developed for people 
with disabilities. 

In 1986, IBM Entry Systems Divi¬ 
sion in Boca Raton formed a new 
development group, Special Needs 
Systems. This group was chartered 
to provide not only products for peo¬ 
ple with disabilities, but also to pro¬ 
vide direction to other IBM product 
development groups. This direction 
helps ensure that people with dis¬ 
abilities have equal access to IBM 
computers. The group’s mission is 
“to enhance the employability of 
and the quality of life for people 
with disabilities through the use of 
IBM technology and products.” 

Special Needs Systems introduced 
Screen Reader Version 1.0 in Janu¬ 
ary 1988. This was the group’s first 
product and the beginning of the In¬ 
dependence Series of products. 

Since then, two additional products 
were announced, as well as enhance¬ 
ments to Screen Reader. These 
products comprise the Independence 
Series today: 

• Screen Reader™ - used by the 
blind and severely visually im¬ 
paired to read screen information. 


• SpeechViewer™ - used as a tool 
by speech therapists for the treat¬ 
ment of speech disorders. 

• PhoneCommunicator™ - used by 
the deaf, severely hearing- and/or 
speech-impaired to communicate 
from an IBM Personal Computer 
to a Telecommunications Device 
for the Deaf (TDD), a Touch 
Tone™ telephone or another per¬ 
sonal computer. 

Screen Reader 

IBM announced Screen Reader Ver¬ 
sion 1.1 in October 1989. This 
product uses a synthesized voice to 
read the text on the computer screen. 

Using the separate 18-key keypad, 
the user sends commands to the 
Screen Reader so that characters, 
words, lines, sentences, or para¬ 
graphs are spoken. The entire 
screen can be read, or Screen 


Reader can automatically read as 
you browse through documents. Ad¬ 
ditionally, keystrokes can be read as 
they are typed. 

Screen Reader contains the follow¬ 
ing features: 

• Automatic monitoring and speak¬ 
ing of screen changes 

• Adjustable reading boundaries on 
the screen 

• Monitoring and speaking of all 
SAA menu selections 

• Special profiles that customize 
Screen Reader for the following 
software applications: 

— IBM Assistant Series® 

- dBASE III Plus™ 

— DisplayWrite4™ 
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Random Data 


- Lotus 1-2-3™ 

— WordPerfect™ 

— 3270 and 3250 emulation pro¬ 
grams 

• Profile Access Language (PAL) 
for creation of custom profiles by 
customers 

• A full-screen utility program for 
changing the preset synthesizer 
values and messages spoken. 

Screen Reader Development: 

Screen Reader represents a signifi¬ 
cant technology transfer from re¬ 
searcher to end-user product. The 
original concept and software devel¬ 
opment for Screen Reader was done 
by research scientists at IBM’s 
Thomas J. Watson Research Center. 
The technology and usability were 
enhanced by Special Needs Systems 
in conjunction with research and 
many IBM users who are blind. 

During Screen Reader development, 
some work was done in conjunction 
with several vendors to provide a 
complete workstation for blind or 
visually impaired people. For the 
first time on a single IBM computer 
system, a user can scan in printed 
documents and read them with 
voice or screen enlargement. 

Two vendors, Arkenstone and 
Kurzweil, have products that can 
scan hardcopy material, such as let¬ 
ters, book pages, and newsprint into 
the computer. Screen Reader can 
then be used to read the scanned in¬ 
formation. 


Vista™ and LP-DOS™ are two pro¬ 
grams that can be used to enlarge 
screen text. Users with partial sight 
then may be able to read the screen 
information. Characters can be en¬ 
larged in synchronization with the 
reading of screen information using 
Screen Reader. 

Documentation: The documenta¬ 
tion for Screen Reader is available 
in four media: 

• Audiocassette 

• Online 

• Print 

• Braille 

The self-paced, online tutorial 
makes learning the basics easy. Ref¬ 
erence material is presented in a 
clear and easy-to-read form. 

Operating Requirements: IBM 

Screen Reader works on the PC XT, 
PC XT 286, Personal Computer AT, 
and all PS/2 models. 

Additionally, the program requires 
IBM DOS version 3.30 or later, 128 
KB system memory, and sufficient 
storage for applications and DOS. 

Compatibility: Screen Reader sup¬ 
ports most commercially available 
text-to-speech synthesizers, includ¬ 
ing the following: 

• Accent™ 

• Apollo™ 

• Audapter™ 


• Calltext 5050 5010™ 

• DECtalk™ 

• Echo PC™ 

• Personal Speech System™ 

• Prose 2020™ 

• TYPE’N TALK™ 

• VoxBox™ 

Support for internal synthesizers 
may be available through some syn¬ 
thesizer manufacturers. 

Screen Reader can use expanded 
memory if it is available on the 
computer. 

Ordering Information: The IBM 

Screen Reader option for the PS/2 
computers (order number 6450616) 
includes: 

• 18-key keypad 

• Keypad cable 

• Program diskettes 

• Online documentation 

• Audiocassettes 

• Printed book 

The IBM Screen Reader option for 
the IBM Personal Computers 
(6450617) includes all of the preced¬ 
ing plus an adapter for IBM per¬ 
sonal computers. 
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The IBM Screen Reader Braille 
Book (6024937) includes Braille 
documentation of the User’s Guide 
and a reference book. 

SpeechViewer 

Special Needs Systems announced 
SpeechViewer, the second member 
of the Independence Series, in No¬ 
vember 1988. SpeechViewer is a 
clinical tool for speech pathologists, 
teachers, and other professionals 
trained in the treatment of speech, 
language, and hearing disorders. 

Using SpeechViewer, speech profes¬ 
sionals can help their clients moni¬ 
tor and gain control over such 
speech attributes as voicing, pitch, 
loudness, vowel pronunciation accu¬ 
racy, and speech timing. 

SpeechViewer hardware and soft¬ 
ware addresses a key element in 
speech therapy: the feedback pro¬ 
cess. SpeechViewer complements 
traditional speech therapy proce¬ 


dures by providing visual and audi¬ 
tory feedback on selected speech at¬ 
tributes. SpeechViewer uses a 
microphone to accept a user’s 
speech sounds. The sounds are digi¬ 
tized, stored, and instantly analyzed 
while providing immediate feed¬ 
back to the user. 

SpeechViewer software consists of 
13 modules accessible from a main 
menu. The diversity of the modules 
makes SpeechViewer appropriate 
for all age ranges and for many 
communication disorders. 
SpeechViewer is easy to use, yet 
flexible. The speech professional 
can customize the modules to meet 
individual client needs. 

The SpeechViewer modules are clas¬ 
sified by their clinical objectives. 

The three classifications are: 

• Awareness - The Awareness 
modules use simple displays and 
employ a cause-and-effeet meth¬ 


odology to focus attention on a 
discrete speech attribute. These 
modules can hold a client’s atten¬ 
tion and provide positive feed¬ 
back about selected attributes of 
speech. For example, with the 
Pitch Awareness module, clients 
can see the mercury in a ther¬ 
mometer rise and fall as their 
pitch rises and falls. 

• Skill Building - The Skill Build¬ 
ing modules use game-like dis¬ 
plays and employ a goal-oriented 
methodology to help the client 
gain control over speech attri¬ 
butes such as pitch, voicing, and 
vowel pronunciation accuracy. 

For example, a client can guide a 
mobile through a maze by accu¬ 
rately pronouncing four different 
vowel sounds. 

• Patterning - The Patterning mod¬ 
ules use technical displays for cre¬ 
ating and matching visual 
representations of speech attri- 
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butes. These modules contain 
technical, quantifiable informa¬ 
tion for critical analysis. 

SpeechViewer Development: 

SpeechViewer is based on more 
than 10 years of research and clini¬ 
cal experience. In 1977, the IBM 
Paris Scientific Center organized a 
research team to create a speech 
training tool for deaf children. The 
first prototype, which used digital 
signal processing technology to ana¬ 
lyze a child’s speech, was installed 
in a school for the deaf in Paris in 
1979. Eventually, prototypes were 
installed in more than 150 locations 
in 29 countries. As technology ad¬ 
vanced and input was received from 
teachers and clinicians using the pro¬ 
totype, the researchers at the Paris 
Scientific Center continued to make 
improvements to the speech training 
tool. 

In 1986, an effort was begun to 
gather data on the clinical effective¬ 
ness of the speech training proto¬ 
type, not only with deaf children, 
but with people of all ages and with 
many types of communication disor¬ 
ders. Testing in hospitals, schools, 
universities, and schools for the 
deaf demonstrated that the programs 
were highly motivating, provided 
critical visual feedback to therapists 
and clients, and could be integrated 
into established and accepted clini¬ 
cal practices. The positive results 
provided the impetus for Special 
Needs Systems to transfer the tech¬ 
nology from the research stage into 
a product. 

Operating Requirements: 

SpeechViewer is designed to run on 
an IBM Personal System/2 Model 
25, 30, and 30-286 (8525 or 8530) 
with the following: 

• IBM DOS 4.00 


• 512KB of system memory 

• One available full-size expansion 
slot for the adapter 

• Graphics printer (optional) 

Compatibility: The SpeechViewer 
program requires exclusive use of 
the system hardware while running. 

Ordering Information: The IBM 

Personal System/2 SpeechViewer 
Convenience Kit (6450610) in¬ 
cludes the SpeechViewer Hardware 
Option and SpeechViewer Applica¬ 
tion Software. 

The IBM Personal System/2 Speech- 
Viewer Hardware Option (6450611) 
includes: 

• SpeechViewer adapter 

• One 3.5-inch diagnostic diskette 

• Hardware Option Installation 
Guide 

• OEM microphone and cable 

• OEM speaker and cable 

• Test plug 

The IBM Personal System/2 Speech- 
Viewer Software Option (6280310) 
includes: 

• User’s Guide 

• Quick Reference 

• Two 3.5-inch application soft¬ 
ware diskettes 

PhoneCommunicator 

The PhoneCommunicator program 
is the newest member of the IBM 
Independence Series. This program 
represents a major step forward in 
providing communication assistance 


to hearing- or speech-impaired peo¬ 
ple. These people now have a prod¬ 
uct to aid them in communicating 
with the hearing world through the 
use of an IBM computer and a stan¬ 
dard touch-tone telephone. It also 
communicates with TDDs, provid¬ 
ing the user a full-screen view of 
the dialogue of both parties. Other 
computer applications may be run¬ 
ning while PhoneCommunicator is 
active. 

PhoneCommunicator 
Development: This product had its 
genesis from the Augmented Phone 
Services program, which was intro¬ 
duced in 1985. Although based on 
the 1985 software, the 
PhoneCommunicator program has 
undergone major enhancements. 
Feedback from IBM internal users 
inspired two of the original develop¬ 
ers to continue enhancing the prod¬ 
uct to satisfy user requirements. 
Their efforts resulted in an IBM in¬ 
ternally released version of the 
product. 

In 1988, an effort was started by the 
Special Needs Systems group in 
Boca Raton to understand the effec¬ 
tiveness of the IBM internal product 
and assess whether it could be en¬ 
hanced to meet the needs of any 
hearing- and/or speech-impaired per¬ 
son. As the development team 
worked, testing began inside IBM 
with hearing- and speech-impaired 
employees, and outside IBM at uni¬ 
versities, deaf service centers, and 
government agencies. The develop¬ 
ment team worked diligently with 
all the test groups to understand and 
incorporate many of their requests 
into the final product. IBM an¬ 
nounced PhoneCommunicator in 
December 1989. 

Product Description: The 

PhoneCommunicator adapter, which 
uses the personal computer bus ar- 


Personal Systems/Issue 2, 1990 


110 


chitecture, provides a synthesized 
voice output to the telephone. The 
program can also provide a modem 
connection to the telephone line for 
communication with a TDD 
(Baudot or ACSII), another com¬ 
puter using the 

PhoneCommunicator program, or an 
ASCII bulletin board service. 

When the user receives a telephone 
call, the screen flashes, visually indi¬ 
cating an incoming call. The user 
can then press a sequence of keys to 
suspend the current application and 
start the PhoneCommunicator 
program. 

The hearing- and/or speech-im¬ 
paired person can read conversa¬ 
tional messages on the screen. 

Those messages can be saved and 
printed. 

PhoneCommunicator contains the 
necessary facilities to access and 
communicate with bulletin board 
services in conversational mode. 

The modem on the 
PhoneCommunicator Adapter can 
be used to transfer ASCII data files 
to and from a host computer. This 
requires Crosstalk™ XVI, Version 
3.61 A, a separately purchased soft¬ 
ware package. 

The program can also be like a tele¬ 
phone answering machine. This al¬ 
lows the user to have incoming 
calls answered by the computer. 
Telephone numbers and messages 
can be left by callers. 

A base vocabulary of 8,500 words 
is standard. These words are used 
to decode the numbers sent from a 
touch-tone telephone into words 
that can be viewed by the user on 


the computer screen. The user can 
append words to the vocabulary. 

Operating Requirements: The 

PhoneCommunicator Hardware 
Adapter is a personal computer bus 
adapter and uses a full-length slot. 

PhoneCommunicator runs on the fol¬ 
lowing IBM computers: 

• Personal Computer 

• Personal Computer XT, except 
XT/370 

• Personal Computer XT-286 

• Personal Computer AT, except 
AT/370 

• Personal System/2 Models 25, 

30, and 30-286 

The computers must have IBM 
DOS version 3.30 or 4.00, 512 KB 
of system memory and one fixed- 
disk drive or two diskette drives. 

Compatibility: With 640 KB of 
memory, programs up to 256 KB 
may be run while 
PhoneCommunicator is active. 

With the separate purchase of 
SoftwareCarousel™ version 3.0, ap¬ 
plications up to 512 KB can 
co-reside with PhoneCommunicator 
in a 640 KB system. 
SoftwareCarousel allows programs 
to be temporarily suspended while a 
telephone call is being made or re¬ 
ceived. No data is lost from the pro¬ 
gram you are working in when you 
suspend the program to make or an¬ 
swer a telephone call. 

Ordering Information: The IBM 

PhoneCommunicator Convenience 
Kit (6450618) includes the 


PhoneCommunicator Hardware and 
Software Options. 

The IBM PhoneCommunicator 
Hardware Option (6450619) in¬ 
cludes: 

• PhoneCommunicator Adapter 

• Hardware installation instructions 

• A 5.25-inch and a 3.5-inch diag¬ 
nostic diskette 

The IBM PhoneCommunicator Ap¬ 
plication Software (57F1954) in¬ 
cludes: 

• PhoneCommunicator Application 
diskettes in both 5.25- and 3.5- 
inch media 

• PhoneCommunicator User’s 
Guide 

• Telephone reference cards (10 
per pack) 

Product Support 

The IBM National Support Center 
for Persons with Disabilities 
(NSCPD) provides technical and 
marketing support for these prod¬ 
ucts. The NSCPD also acts as a 
clearing house for information on 
other products and agencies that as¬ 
sist people with disabilities. The 
NSCPD can be contacted at 
1 800 426-2133; or if using a TDD, 
at 1 800 284-9482. 

The Independence Series products 
are available only through IBM 
TeleMarketing Operations. Product 
orders can be placed by calling 
1 800 426-3388 (voice calls) or 
1 800 426-3383 (TDD calls). If 
calling from Canada, dial 
1 800 465-1234. 
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New Products 

Hardware 

IBM PS/2 Model 70 486 
(8570-B61 and 8570-B21) 

The Personal System/2 Model 70 486 
(8570-B61 and 8570-B21), with a 25 
MHz i486™ 32-bit microprocessor, en¬ 
hanced the PS/2 family of systems by of¬ 
fering a new level of advanced 
performance in a desktop unit. The 
Model 70 486 includes a 25 Mhz i486 
32-bit microprocessor that features an in¬ 
ternal memory cache controller, an inter¬ 
nal 8 KB memory cache, and an internal 
floating-point processing unit to perform 
the functions of external 80387 Math 
Co-Processor. 

The Model 70 386 (8570-A61 and 8570- 
A21) can be upgraded to the Model 70 
486 by the installation of the 486/25 
Power Platform. 

The Model 70 486 is appropriate for ad¬ 
vanced users who perform 
numeric-intensive applications requiring 
floating-point operations, or large mem¬ 
ory resident applications that will bene¬ 
fit from the advanced processing 
capabilities of the 25 Mhz i486 32-bit 
microprocessor. 

The Model 70 486 is compatible with 
most existing software products for IBM 
personal computer and Personal Sys¬ 
tem/2 systems. Due to the higher speed 
of the i486 processor in the Model 70 
486, some timing sensitive software 
may require modification. 

The Model 70 486 is supported by Oper¬ 
ating System/2 (OS/2) Standard Edition 
1.1 and 1.2, OS/2 Extended Edition 1.1 
and 1.2, and the Disk Operating System 
(DOS) Version 3.3 and 4.0. Corrective 
Service Diskette UR 25066 is required 
to support Expanded Memory Specifica¬ 
tion (EMS) with DOS 4.0. 

Highlights: 

• 25 MHz i486 32-bit microprocessor 


• Internal memory cache controller and 
8 KB internal memory cache 

• Internal floating-point unit replaces 
need for external 80387 

• System board memory expandable to 
8 MB 

• 60 MB or 120 MB fixed disk with in¬ 
tegrated controller 

• Micro Channel™ Architecture with 
one 16-bit and two 32-bit slots 

• Well-suited for applications such as 
engineering/scientific, image process¬ 
ing, financial modeling, software de¬ 
velopment, and other 
numeric-intensive applications 

• Software compatibility with 80386 
systems 

• Upgrade capability from Model 70 
386 (8570-A61/A21). 

IBM Token-Ring Network 
PS/2 Model P70 386 
Adapter/A 

The IBM Token-Ring Network PS/2 
Model P70 386 Adapter/A (feature code 
#1598) permits attachment of the IBM 
PS/2 Model P70 386 (8573-061 and 
8573-121) to the IBM Token-Ring Net¬ 
work. This adapter is half-length and 
designed to fit in the short slot. It trans¬ 
mits and receives at 4 million bits per 
second using protocols conforming to 
IEEE 802.5 and ECMA 89 standards. 
The adapter provides logical link control 
functions conforming with the IEEE 
802.2 standard and is compatible with 
International Standard ISO - 8802/5. It 
provides 16 KB of RAM and all of the 
function of the IBM Token-Ring Net¬ 
work Adapter/A (feature code #4790). 
To facilitate attachment to the IBM PS/2 
P70 386, a unique L angle connector 
with a permanently attached short cable 
is provided. 

Highlights: 

• Provides 16 KB of RAM 


• Designed for use in half-length slot 

• Compatible with International Stan¬ 
dard ISO-8802/5 

• Unique L angle connector with per¬ 
manently attached short cable 

M-Motion Video Adapter/A 
For The IBM Personal 

System/2 

The M-Motion Video Adapter/A is an 
Personal System/2 Micro Channel 
adapter card that allows Micro Channel 
PS/2s to display full motion, interactive 
color video on standard color PS/2 moni¬ 
tors. This adapter card also provides 
full-line audio and limited digital audio 
capabilities. The M-Motion Video 
Adapter/A receives analog signals from 
an audio-video source, processes the sig¬ 
nals, and sends them to a PS/2 monitor 
and speaker. The M-Motion Video 
Adapter/A is designed to support all ex¬ 
isting InfoWindow™ applications. 

Highlights: 

• Produces interactive full motion 
color video and audio on PS/2 Micro 
Channel systems 

• Produces windowed video on color 
PS/2 monitors 

• Allows two high-quality stereo inputs 
as well as three NTSC/PAL video in¬ 
puts or two Super VHS video inputs 

• Allows recording and playback of 
narrative quality audio to and from a 
DASD device 

• Supports all VGA modes (640 x 480 
pixels) 

• Includes multiple connector cable al¬ 
lowing input from audio and video 
devices provided 

• Allows computer control of video 
and audio functions (for example, 
source selection, volume, tone, 
windowing, color, brightness, hue, 
saturation contrast, etc.) 
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IBM Store Controller Kit 
for IBM PS/2 Model 55 SX 

The IBM Store Controller Kit allows 
the IBM PS/2 Model 55 SX (8555-031 
or 8555-061) with the IBM 4680 Operat¬ 
ing System Version 2 (5601-192) to be¬ 
come a store controller for the IBM 
4680 Store System. The Second Store 
Loop Adapter/A option monitors an¬ 
other store loop's activity and, with the 
4680 Operation System, takes control of 
the monitored loop if it detects a lack of 
store controller activity. 

Highlights: 

• Lower entry price store controller 

• Internal speed and memory capacities 
of PS/2 

• User can upgrade installed PS/2 ma¬ 
chines 

• Token-Ring Networking to service 
multicontroller - PS/2 and PC AT® 
store controllers with the same Net¬ 
work Master 

• Support of selected PS/2 options 

Software 

NetView/PC Version 
Available with Additional 
Function 

NetView ™/PC Version 1.2.1 (English 
version) provides additional function 
and will be available on March 30, 

1990, to coincide with Operating Sys¬ 
tem/2 Extended Edition (OS/2) EE Ver¬ 
sion 1.2 availability. 

NetView/PC is an extension of the Com¬ 
munication Network Management 
(CNM) services provided by NetView. 

It is enhanced to installing Network/PC 
Gateway function and the option of se¬ 
lectively installing Network/PC the Net¬ 
View/PC Gateway function, or both. 

The Remote Console Facility may be 
also be installed with the functions. 

With the NetView/PC Gateway func¬ 


tion, those customers who require a 
screen-less NetView/PC may install 
only the NetView/PC application pro¬ 
gramming interface/communication sys¬ 
tem (API/CS) function. It allows 
vendor applications to provide a single 
user interface, and continues to provide 
base gateway services to NetView for 
IBM and vendor applications managing 
non-SNA equipment. 

Highlights: 

• Screenless NetView/PC Gateway: 

— Provides an API/CS for writing ap¬ 
plications 

— Allows vendor applications to pro¬ 
vide a single user interface 

— Allows operation in an unattended 
environment 

— Provides optional alert logging ca¬ 
pability 

— Requires fewer system resources 

• Installation Options — The user may 
install NetView/PC, the NetView /PC 
Gateway function, or both, with or 
without Remote Console Facility. 

IBM DataInterchange/2 
Availability 

IBM DataInterchange/2 provides transla¬ 
tion and business document manage¬ 
ment facilities for Electronic Data 
Interchange (EDI) in Systems Applica¬ 
tion Architecture™ (SAA ™) operating 
system environments. The translation fa¬ 
cility includes a utility for converting ap¬ 
plication data formats into or from U.S. 
EDI standards (ANSI XI2) and interna¬ 
tional EDI standards (EDIFACT and 
UN/TDI). Standard updates are pro¬ 
vided and maintained as a part of the 
product. 

DataIntemational/2 can be tailored for 
different application data formats, stan¬ 
dard transactions, trading partners, and 
network parameters via online transac¬ 
tions, trading partners, and network pa¬ 
rameters via online customization. It 


can be integrated with existing or new 
application or can be operated as a 
stand-alone application. 

DataInterchange/2 provides the capabil¬ 
ity to read application data from a file 
or write to a file, that can be uploaded 
or downloaded to other systems. The 
product also includes facilities for log¬ 
ging, error recovery and security. 

M-Control Program 

The IBM M-Control Program includes 
program interfaces for DOS and an 
OS/2 Presentation Manager toolkit. The 
M-Control Program provides functional 
support for application developers who 
want to use PS/2 model configurations 
containing the following multimedia fea¬ 
tures: 

• Models 50, 50Z, 55SX, 60, 70, and 
80 

— M-Video Adapter/A for the IBM 
PS/2 

• Supported models of videodisc play¬ 
ers as audio and/or video storage de¬ 
vices 

The DOS program interfaces support the 
InfoWindow™ Touch Display Control 
Program function that applies to the 
M-Motion Video Adapter/A for the 
PS/2. 

The OS/2 Toolkit Dynamic Link Librar¬ 
ies (DDL) provide OS/2 Presentation 
Manager objects and messaging inter¬ 
faces for video control. The toolkit also 
includes a sample multimedia applica¬ 
tion, with source code, demonstrating 
use of toolkit functions. 

Highlights: 

• Allows programmers the ability to 
control multimedia devices such as 
video and audio 

• Allows programmers the ability to 
create pointer device drivers that 
meet PS/2 pointer interface require¬ 
ments such as mouse, touchscreen or 
other 
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• Supports the M-Motion Video 
Adapter/A for the PS/2 that provides 
scalable full-motion video with 
graphic overlay 

• Supports multiple RS-232C serial in¬ 
terfaced videodisc players 

• Supports both NTSC and PAL video 
standards 

• Supports the part of the InfoWindow 
Touch Display Control Program func¬ 
tion that applies to the M-Motion 
Video Adapter/A for the PS/2 

IBM LinkWay Multimedia 
Tools 

IBM LinkWay Multimedia Tools pro¬ 
vide LinkWay application developers 
functional support for the following mul¬ 
timedia features: 

• Personal System/2 Audio Cap¬ 
ture/Playback Adapter/A 

• PS/2 Audio Capture/Playback Adapter 

• M-Motion Video Adapter/A for the 
IBM Personal System/2 

• Supported Videodisc Player models 
for video display 

The LinkWay Multimedia Tools must 
be used with IBM LinkWay. 

Highlights: 

• Allows developers the ability to con¬ 
trol multimedia devices such as video 
and audio 

• Expands the ability of developers to 
create multimedia applications using 
IBM LinkWay 

• Supports the M-Motion Video 
Adapter/A for the PS/2 and the PS/2 
Audio Capture/Playback Adapter/A 
that provide high-quality audio and 
scalable full-motion video with 
graphic overlay 

• Multiple RS-232C serial interfaced 
videodisc players supported 


IBM Storyboard Plus 
Version 2.00 LAN Pack 

The Storyboard™ Plus Version 2.00 
LAN Pack Licensed program is a multi- 
media application offering for qualified 
educational institutions. It combines 
drawing, painting, text, still audiovisual 
presentations on an IBM Personal Com¬ 
puter, certified IBM compatible com¬ 
puter, or Personal System/2 (PS/2) 
system. 

The Storyboard Plus Version 2.00 LAN 
Pack may be used under control of a 
local area network program, concur¬ 
rently on up to 50 machines including 
one server machine that controls the net¬ 
work. 

Highlights: 

• Functions to enhance picture and 
story editing capabilities 

• Support for a number of video cap¬ 
ture interface cards 

• Support for additional printers, in¬ 
cluding additional color printers 

• Support for the IBM 8514/A Video 
Adapter in 640 x 480 - 256 color 
mode 

• Ability to mix display resolutions 
within a presentation 

Software Carousel Version 
3.01 Lotus 1-2-3 Release 2.2 

Software Carousel® 3.01 provides mem¬ 
ory relief to permit large DOS applica¬ 
tions to run in the DOS task area when 
operating with Workstation Connectiv¬ 
ity Memory Management Enhancement 
program offering 83X9133. The func¬ 
tions provided by Software Carousel 
and Workstation Connectivity Memory 
Management Enhancement allow a user 
to free up to approximately 400-500 K 
of memory for application use. It is rec¬ 
ommended that the programming an¬ 
nouncement for Workstation 
Connectivity Memory Management En¬ 
hancement be reviewed to ensure that it 
is appropriate for your environment. 


Software Carousel 3.01 used in conjunc¬ 
tion with the IBM Workstation Connec¬ 
tivity Memory Management 
Enhancement program supports the fol¬ 
lowing IBM Program/Product An¬ 
nouncement offerings: 

• IBM Personal Communications/3270 

• PC/HOST File Transfer and Termi¬ 
nal Emulator Program Version 2.1 

• IBM Personal System/2 Expanded 
Memory Options 

• Application System/400™ 

(AS/400™) PC Support Release 2 

Software Carousel allows you to load 
up to 12 programs, and work with all 12 
at once. In a local area network (LAN) 
environment, a workstation user can 
have a host connectivity program, a 
spreadsheet program, a word processing 
program, a data base program and oth¬ 
ers in different partitions, only one of 
which will be active at a given time. 
Programs are stored in expanded or ex¬ 
tended Random Access Memory 
(RAM), or in a disk file while inactive. 
All of lower RAM is available to each 
program you run. A menu-driven, 
fill-in-the-blanks, configuration program 
makes automating your system quick 
and easy. 

Highlights: 

• Compatible with virtually every PC 
programs. 

• Solves conflicts with using many 
RAM-resident programs. 

• Makes full use of expanded and ex¬ 
tended memory for lightning-fast 
switching between programs. 

• Completely user-configurable so com¬ 
mand keys never conflict with other 
programs like WordPerfect or Side- 
kick. 

Lotus 1-2-3 Release 2.2 (3.5-inch and 
5.25-inch) 
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• The add-in Manager has been built 
into Release 2.2 as a main-menu item 
making it easy to use existing 1-2-3 
add-ins. The user can now hook or 
un-hook add-in functionally as 
needed. 

• The Lotus Learn add-in has been 
built into Release 2.2 proving a 
method of recording keystrokes for 
easy macro creation. 

• The Macro Library Manager add-in 
allows for safe, off-sheet storage of 
macros. The user can run macros 
from the Macro Library Manager in 
the current file. The Library can con¬ 
tain macros, formulas, ranges or en¬ 
tire applications. 

• Enhanced STEP mode displays 
macro commands at the bottom of 
the screen as the user “steps” through 
the execution of a macro. Allows the 
user to test automated routines and 
quickly debug macros. 

• Undo is an error correction mecha¬ 
nism that allows users to reverse 
changes made to the worksheet since 
1-2-3 was last in ready mode. 

• Search and Replace allows users to 
find and replace any string that is lo¬ 
cated within a formula and/or label 
entry. 

• Spreadsheet publishing with Allways 
has been incorporated into Release 
2.2. Allways is an add-ins that al¬ 
lows users to prepare typeset quality 
output with mixed text and graphics 
directly from within the spreadsheet. 

MERVA/2 Version 2 

The IBM Message Entry and Routing 
with Interfaces to Various Applications 
(MERVA)/2 licensed program replaces 
MERVA/2 Version 1 including the 
Multi MERVA workstation feature and 
the associated product Direct S.W.I.F.T. 
Network Link (DSNL)/2 Version 1. 
MERVA/2 Version 2 integrates all the 
functions necessary to support connec¬ 
tions to the SWIFT I and SWIFT II net¬ 
works [the worldwide private networks 


defined and maintained by the Society 
for Worldwide Interbank Financial Tele¬ 
communication (SWIFT)], as well as to 
Telex networks and other MERVA in¬ 
stallations (on PS/2 or System/370). 
MERVA/2 Version 2 operates under 
OS/2 Extended Edition 1.2. 

To allow consideration of test results 
with the new SWIFT II network, gen¬ 
eral availability of MERVA/2 Version 2 
will be announced in April 1990. 

Highlights: 

• Integrated solution covering the fol¬ 
lowing functions: 

— SWIFT I and SWIFT II network 
support 

— Telex network support via the PS/2 

— MERVA to MERVA connection 
between PS/2 and PS/2 as well as 
between PS/2 and System/370 
MVS-CICS and VSE-CICS 

• Support of new and changed mes¬ 
sage types, to be implemented by 
S.W.I.F.T. until general availability 
of MERVA/2 Version 2 

IBM Plant Floor Series 
Plantworks: Application 
Automation Edition 

The IBM Plant Floor Series™ 
PlantWorks™: Application Automation 
Edition™ consists of the Execution Ser¬ 
vices/2, Build Services/2, Definition Ser¬ 
vices/2, and Interfaces Services/2 
licensed programs. PlantWorks pro¬ 
vides a distributed, plant-floor supervi¬ 
sory facilities for monitoring and 
controlling plant floor equipment. It in¬ 
cludes an application creation capability 
for the non-programmer and a set of ap¬ 
plication execution functions. 
PlantWorks executes on specified IBM 
Operating System/2 (OS/2) Extended 
Edition and Plant Floor Series Distrib¬ 
uted Automation Edition. 


Plant Floor Series 
Distributed Automation 
Edition™ Entry 
Communications System/2 

Plant Floor Series Distributed Automa¬ 
tion Edition is a set of licensed pro¬ 
grams that provides a standard 
application interface to plant floor de¬ 
vices and other communication facilities. 

Entry Communications System/2, which 
addresses workstation requirements, is 
added to the Distributed Automation 
Edition. It allows the user to develop 
manufacturing or process control appli¬ 
cations on IBM industrial computers, 
IBM personal computers, or IBM Per¬ 
sonal System/2, using the Operating Sys¬ 
tem/2 (OS/2 Extended Edition (EE)). 
Entry Communications System/2 may 
be upgraded to Communications Sys¬ 
tem/2. 

Highlights: 

• Communications between programs 
anywhere in a network of IBM indus¬ 
trial computers, IBM personal com¬ 
puters, Personal System/2 computers, 
and ES/9370 

• Communication and management ca¬ 
pabilities to support plant floor de¬ 
vices, such a robots, bar code 
readers, programmable controllers, 
and plant floor data collection termi¬ 
nals, using the IBM Real Time Inter¬ 
face Co-processor resident in a 
remote Communications System/2 
node 

• Routing and management of plant 
floor data and programs 

• Resource management through logi¬ 
cal views rather than through com¬ 
plex physical characteristics 

• Application program interfaces (API) 
for use of high-level program lan¬ 
guages 

• System services for print spooling, 
logging, network/node initialization, 
and shutdown 
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• Interoperability support between VM 
and OS/2 EE platforms 

• Future Manufacturing Automation 
Protocol (MAP)(1) and OSI Manufac¬ 
turing Messaging Services (MMS) 
support 

• Relationship to the IBM Computer In¬ 
tegrated Manufacturing (CIM) Archi¬ 
tecture and Systems Application 
Architecture™ SAA™ 

(1) MAP is an acronym of the General 
Motors Corporation to identify its Manu¬ 
facturing Automation Protocol. 

SolutionPac Writing to 
Read Center V2 

The SolutionPac™ Writing to Read® 
Center Version 2 allows more flexibility 
for customers to customize their labs 
based on the number of students, from 
as few as eight students to as many as 
40 students per class, in increments of 
eight-student blocks. The new configu¬ 
ration options of the SolutionPac Writ¬ 
ing to Read Center Version 2 make it 
possible to reach schools and students 
not previously accommodated by the ini¬ 
tially announced configuration. 

Highlights: 

• A Combination of the Personal Sys¬ 
tem/2 (PS/2) Model 25 computers, 
Proprinter® II, Listening Library 
books, cassette players and headsets, 
and Writing to Read and other soft¬ 
ware 

• Additional copies of Primary Editor 
Plus (PEP) program diskettes and for¬ 
matted story diskettes are included 

• On request, Installation/Training Op¬ 
tion Services are available at no 
charge from an IBM Authorized Edu¬ 
cation Specialist (for the PS/2 equip¬ 
ment only) 

• Customer support for the application 
software is provided through a toll- 
free number. 


Exploring Measurement, 
Time, & Money - Level II 
Version 1.00 

Exploring Measurement, Time, and 
Money - Level II Version 1.00 is de¬ 
signed for students working at the third- 
and fourth-grade level. This program 
provides exploratory, structured, and 
construction activities for the content 
areas of measurement, time, and money. 

Exploring Measurement, 
Time, & Money - Level III 
Version 1.00 

Exploring Measurement, Time, and 
Money - Level III Version 1.00 is de¬ 
signed for students working at the fifth- 
and sixth-grade level. This program pro¬ 
vides exploratory, structured, and con¬ 
struction activities for the content areas 
of measurement, time, and money. 

IBM Interleaf™ Publisher 
Version 1 Release 1 

IBM Interleaf Publisher Version 1 Re¬ 
lease 1 contains the following additional 
features not contained in the previous 
version: 

• Novell Netware™ Version 2.12 sup¬ 
port 

• Math Equation formatting and editing 

• Continuous tone image editing (gray 
scale) 

• Reduced disk storage requirements 

• Enhanced import capabilities (TIFF, 
RFT/DCA, HPGL, EPS) 

• IBM Personal Page Printer II 
Sheetfeed option support 

IBM Standard Generalized 
Markup TextWrite 
Operating System/2 Edition 
Limited Availability 

Standard Generalized Markup Language 
(SGML) TextWrite Operating System/2 
(OS/2) Edition will be available Febru¬ 


ary 23, 1990, for OS/2 Standard Edition 
1.2 users, on a limited basis. 

General availability for SGML 
TextWrite on both OS/2 Standard Edi¬ 
tion Version 1.2 and OS/2 Extended Edi¬ 
tion Version 1.2 and OS/2 Extended 
Edition Version 1.2 will be April 27, 
1990. 

The following is more specific informa¬ 
tion about the validation function pro¬ 
vided in SGML TextWrite OS/2 Edition: 

• SGML TextWrite highlights any tags 
that are entered out of a valid con¬ 
text, as specified by the Document 
Type Definition (DTD). 

• The user can also invoke a back¬ 
ground process in the editor to vali¬ 
date the entire file for full 
compliance with the DTD according 
to International Standard (ISO) 8879. 

IBM AIX PS/2 Personal 
graPHIGS Programming 
Interface Version 2 

IBM announces the availability of AIX 
Personal System/2 (PS/2) Personal gra¬ 
PHIGS Programming Interface Version 
2. In addition to previously announced 
capabilities, an installable option and 
supporting documentation is provided 
that allows applications written to the 
Graphical Kernel System (GKS) Interna¬ 
tional Standard (ISO 7942) to run on the 
product. 

Highlights: 

• Graphical Kernel System-Compatibil¬ 
ity Option and associated documenta¬ 
tion 

• The option to run in X-Windows will 
be supported until AIX PS/2 Operat¬ 
ing System Version 1.2 becomes 
available 
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In addition to large memory addressing, productivity gains within the OS/2 
envir onment come from multitask ing a nd multith readin g, (page 5 )_ 


A major enhancement is the new dual boot 
capability, (page 10) 


OS/2’s architecture lays the groundwork for much tighter coordination 
among different tasks on a user's desktop, (page 17) 


It is possible to develop fully object-oriented applications with C 
under the control of OS/2 Presentation Manager, (page 22) 


RDS is designed for multiuser access to a 
database, (page 36) 


The precompiler maintains a list of all host 
variables, (page 51) 


Procedures Language 2/REXX has a free 
format syntax, (page 67) 


This article suggests steps that can be taken to make APPC 
applications run as fast as possible in OS/2, (page 80) 


The RPG II Platform adds an exciting capability 
for the Personal System/2, (page 105) 
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